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

ENGDOCS-2515 (#22347) 

<!--Delete sections as needed -->

## Description

Freshness to DD setup section.

The odd new sentence here and there, but mostly efficiency gains and
tidying

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

---------

Co-authored-by: Sarah Sanders <sarah.sanders@docker.com>
This commit is contained in:
Allie Sadler 2025-04-03 14:39:55 +01:00 committed by GitHub
parent 72cd41d940
commit 936fad5e49
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
19 changed files with 226 additions and 289 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
_vale/Docker/Acronyms.yml
View File

@ -50,6 +50,7 @@ exceptions:
- GDB
- GET
- GHSA
- GNOME
- GNU
- GPG
- GPL
@ -74,10 +75,12 @@ exceptions:
- JIT
- JSON
- JSX
- KDE
- LESS
- LLDB
- LTS
- MAC
- MATE
- MCP
- mcp
- MDM

26
content/manuals/desktop/_index.md
View File

@ -15,10 +15,14 @@ grid:
[Windows](/desktop/setup/install/windows-install/), or
[Linux](/desktop/setup/install/linux/).
icon: download
- title: Explore Docker Desktop
description: Navigate Docker Desktop and learn about its key features.
- title: Learn about Docker Desktop
description: Navigate Docker Desktop.
icon: feature_search
link: /desktop/use-desktop/
- title: Explore its key features
description: |
Find information about [Docker VMM](/desktop/features/vmm/), [WSL](/desktop/features/wsl/), [deploying on Kubernetes](/desktop/features/kubernetes/), and more.
icon: category
- title: View the release notes
description: Find out about new features, improvements, and bug fixes.
icon: note_add
@ -27,11 +31,6 @@ grid:
description: Explore general FAQs or FAQs for specific platforms.
icon: help
link: /desktop/troubleshoot-and-support/faqs/general/
- title: Find additional resources
description: |
Find information on networking features, deploying on Kubernetes, and more.
icon: category
link: /desktop/features/kubernetes/
- title: Give feedback
description: Provide feedback on Docker Desktop or Docker Desktop features.
icon: sms
@ -51,15 +50,18 @@ It provides a straightforward GUI (Graphical User Interface) that lets you manag
Docker Desktop reduces the time spent on complex setups so you can focus on writing code. It takes care of port mappings, file system concerns, and other default settings, and is regularly updated with bug fixes and security updates.
Docker Desktop integrates with your preferred development tools and languages, and gives you access to a vast ecosystem of trusted images and templates via Docker Hub. This empowers teams to accelerate development, automate builds, enable CI/CD workflows, and collaborate securely through shared repositories.
{{< tabs >}}
{{< tab name="What's included in Docker Desktop?" >}}
- [Docker Engine](/manuals/engine/_index.md)
- Docker CLI client
- [Docker Scout](../scout/_index.md) (additional subscription may apply)
- [Docker Scout](../scout/_index.md)
- [Docker Build](/manuals/build/_index.md)
- [Docker Extensions](../extensions/_index.md)
- [Docker Compose](/manuals/compose/_index.md)
- [Ask Gordon](/manuals/desktop/features/gordon/_index.md)
- [Docker Extensions](../extensions/_index.md)
- [Docker Content Trust](/manuals/engine/security/trust/_index.md)
- [Kubernetes](https://github.com/kubernetes/kubernetes/)
- [Credential Helper](https://github.com/docker/docker-credential-helpers/)
@ -78,10 +80,4 @@ Docker Desktop reduces the time spent on complex setups so you can focus on writ
{{< /tab >}}
{{< /tabs >}}
Docker Desktop works with your choice of development tools and languages and
gives you access to a vast library of certified images and templates in
[Docker Hub](https://hub.docker.com/). This allows development teams to extend
their environment to rapidly auto-build, continuously integrate, and collaborate
using a secure repository.
{{< grid >}}

13
content/manuals/desktop/setup/install/enterprise-deployment/faq.md
View File

@ -1,5 +1,6 @@
---
title: Enterprise deployment FAQs
linkTitle: FAQs
description: Frequently asked questions for deploying Docker Desktop at scale
keywords: msi, deploy, docker desktop, faqs, pkg, mdm, jamf, intune, windows, mac, enterprise, admin
tags: [FAQ, admin]
@ -10,11 +11,15 @@ aliases:
## MSI
Common questions about installing Docker Desktop using the MSI installer.
### What happens to user data if they have an older Docker Desktop installation (i.e. `.exe`)?
If they have an older `.exe` installation, users must [uninstall](/manuals/desktop/uninstall.md) this version before using the new MSI version. This deletes all Docker containers, images, volumes, and other Docker-related data local to the machine, and removes the files generated by the application. For older versions, users should [backup](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) any containers that they want to keep.
Users must [uninstall](/manuals/desktop/uninstall.md) older `.exe` installations before using the new MSI version. This deletes all Docker containers, images, volumes, and other Docker-related data local to the machine, and removes the files generated by Docker Desktop.
For Docker Desktop versions 4.30 and later of the `exe` installer, a `-keep-data` flag is available. It removes Docker Desktop but keeps underlying data, such as the VMs that run containers.
To preserve existing data before uninstalling, users should [backup](/manuals/desktop/settings-and-maintenance/backup-and-restore.md) their containers and volumes.
For Docker Desktop 4.30 and later, the `.exe` installer includes a `-keep-data` flag that removes Docker Desktop while preserving underlying resources such as the container VMs:
```powershell
& 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall -keep-data
@ -22,11 +27,11 @@ For Docker Desktop versions 4.30 and later of the `exe` installer, a `-keep-data
### What happens if the user's machine has an older `.exe` installation?
The new MSI installer checks if a previous version was installed and doesn't proceed with the installation. Instead, it prompts the user to uninstall their current/old version first, before retrying to install the MSI version.
The MSI installer detects older `.exe` installations and blocks the installation until the previous version is uninstalled. It prompts the user to uninstall their current/old version first, before retrying to install the MSI version.
### My installation failed, how do I find out what happened?
MSI installations can sometimes fail unexpectedly and not provide users with much information about what went wrong.
MSI installations may fail silently, offering little diagnostic feedback.
To debug a failed installation, run the install again with verbose logging enabled:

20
content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md
View File

@ -1,5 +1,5 @@
---
title: Use the MSI installer
title: MSI installer
description: Understand how to use the MSI installer. Also explore additional configuration options.
keywords: msi, windows, docker desktop, install, deploy, configure, admin, mdm
tags: [admin]
@ -21,7 +21,7 @@ The MSI package supports various MDM (Mobile Device Management) solutions, makin
2. Under **Docker Desktop**, select the **Deploy** page.
3. From the **Windows OS** tab, select the **Download MSI installer** button.
4. Once downloaded, double-click `Docker Desktop Installer.msi` to run the installer.
5. Once you've accepted the license agreement, you can choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`.
5. After accepting the license agreement, choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`.
6. Configure the Docker Desktop installation. You can:
- Create a desktop shortcut
@ -30,11 +30,11 @@ The MSI package supports various MDM (Mobile Device Management) solutions, makin
- Disable Windows Container usage
- Select the engine for Docker Desktop. Either WSL or Hyper-V. If your system only supports one of the two options, you won't be able to select which backend to use.
- Select the Docker Desktop backend: WSL or Hyper-V. If only one is supported by your system, you won't be able to choose.
7. Follow the instructions on the installation wizard to authorize the installer and proceed with the install.
8. When the installation is successful, select **Finish** to complete the installation process.
If your administrator account is different to your user account, you must add the user to the **docker-users** group:
If your administrator account is different from your user account, you must add the user to the **docker-users** group:
1. Run **Computer Management** as an **administrator**.
2. Navigate to **Local Users and Groups** > **Groups** > **docker-users**.
3. Right-click to add the user to the group.
@ -42,7 +42,7 @@ If your administrator account is different to your user account, you must add th
> [!NOTE]
>
> When installing Docker Desktop with the MSI, in-app updates are automatically disabled. This feature ensures your organization maintains the required Docker Desktop version. For Docker Desktop installed with the .exe installer, in-app updates remain supported.
> When installing Docker Desktop with the MSI, in-app updates are automatically disabled. This ensures organizations can maintain version consistency and prevent unapproved updates. For Docker Desktop installed with the .exe installer, in-app updates remain supported.
>
> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Deploy** page > under **Docker Desktop**.
>
@ -116,7 +116,7 @@ msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /passive /norestart
> [!TIP]
>
> Some useful tips to remember when creating a value that expects a JSON string as it’s value:
> When creating a value that expects a JSON string:
>
> - The property expects a JSON formatted string
> - The string should be wrapped in double quotes
@ -142,7 +142,7 @@ IdentifyingNumber Name
```
> [!NOTE]
>
> This command can take some time to return, depending on the number of installed applications.
> This command may take some time, depending on the number of installed applications.
`IdentifyingNumber` is the applications product code and can be used to uninstall Docker Desktop. For example:
@ -202,11 +202,11 @@ msiexec /x "DockerDesktop.msi" /quiet
Additionally, you can also use `/norestart` or `/forcerestart` to control reboot behaviour.
By default, the installer reboots the machine after a successful installation. When ran silently, the reboot is automatic and the user is not prompted.
By default, the installer reboots the machine after a successful installation. When run silently, the reboot is automatic and the user is not prompted.
## Analytics
The MSI installer collects anonymous usage statistics relating to install only. This is to better understand user behaviour and to improve the user experience by identifying and addressing issues or optimizing popular features.
The MSI installer collects anonymous usage statistics relating to installation only. This is to better understand user behaviour and to improve the user experience by identifying and addressing issues or optimizing popular features.
### How to opt-out
@ -239,7 +239,7 @@ The registry key is as follows:
SOFTWARE\Docker Inc.\Docker Desktop\DisableMsiAnalytics
```
When analytics is disabled, this key has a value of `1`.
When analytics is disabled, this key is set to `1`.
## Additional resources

18
content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md
View File

@ -1,5 +1,5 @@
---
title: Use the PKG installer
title: PKG installer
description: Understand how to use the PKG installer. Also explore additional configuration options.
keywords: pkg, mac, docker desktop, install, deploy, configure, admin, mdm
tags: [admin]
@ -16,17 +16,17 @@ The PKG package supports various MDM (Mobile Device Management) solutions, makin
2. Under **Docker Desktop**, select the **Deploy** page.
3. From the **macOS** tab, select the **Download PKG installer** button.
4. Once downloaded, double-click `Docker.pkg` to run the installer.
5. Follow the instructions on the installation wizard to authorize the installer and proceed with the install.
- **Introduction**: Select `Continue`.
- **License**: Review the license agreement and select `Agree`.
- **Destination Select**: This step is optional. It is recommended that you don't change the default installation destination (usually `Macintosh HD`). Select `Continue`.
- **Installation Type**: Select `Install`.
5. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation.
- **Introduction**: Select **Continue**.
- **License**: Review the license agreement and select **Agree**.
- **Destination Select**: This step is optional. It is recommended that you keep the default installation destination (usually `Macintosh HD`). Select **Continue**.
- **Installation Type**: Select **Install**.
- **Installation**: Authenticate using your administrator password or Touch ID.
- **Summary**: After the installation completes, select `Close`.
- **Summary**: When the installation completes, select **Close**.
> [!NOTE]
>
> When installing Docker Desktop with the PKG, in-app updates are automatically disabled. This feature ensures your organization maintains the required Docker Desktop version. For Docker Desktop installed with the .dmg installer, in-app updates remain supported.
> When installing Docker Desktop with the PKG, in-app updates are automatically disabled. This ensures organizations can maintain version consistency and prevent unapproved updates. For Docker Desktop installed with the `.dmg` installer, in-app updates remain supported.
>
> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Deploy** page > under **Docker Desktop**.
>
@ -45,5 +45,5 @@ The PKG package supports various MDM (Mobile Device Management) solutions, makin
## Additional resources
- See how you can deploy Docker Desktop for Mac via [Intune](use-intune.md) or [Jamf Pro](use-jamf-pro.md)
- See how you can deploy Docker Desktop for Mac using [Intune](use-intune.md) or [Jamf Pro](use-jamf-pro.md)
- Explore how to [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/methods.md#plist-method-mac-only) for your users.

14
content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md
View File

@ -1,5 +1,5 @@
---
title: Use Intune
title: Deploy with Intune
description: Use Intune, Microsoft's cloud-based device management tool, to deploy Docker Desktop
keywords: microsoft, windows, docker desktop, deploy, mdm, enterprise, administrator, mac, pkg, dmg
tags: [admin]
@ -11,7 +11,7 @@ aliases:
{{< summary-bar feature_name="Intune" >}}
Learn how to deploy Docker Desktop for Windows and Mac using Intune, Microsoft's cloud-based device management tool.
Learn how to deploy Docker Desktop on Windows and macOS devices using Microsoft Intune. It covers app creation, installer configuration, and assignment to users or devices.
{{< tabs >}}
{{< tab name="Windows" >}}
@ -20,7 +20,7 @@ Learn how to deploy Docker Desktop for Windows and Mac using Intune, Microsoft's
2. Add a new app. Select **Apps**, then **Windows**, then **Add**.
3. For the app type, select **Windows app (Win32)**
4. Select the `intunewin` package.
5. Complete any relevant details such as the description, publisher, or app version and then select **Next**.
5. Fill in the required details, such as the description, publisher, or app version and then select **Next**.
6. Optional: On the **Program** tab, you can update the **Install command** field to suit your needs. The field is pre-populated with `msiexec /i "DockerDesktop.msi" /qn`. See the [Common installation scenarios](msi-install-and-configure.md) for examples on the changes you can make.
> [!TIP]
@ -29,9 +29,9 @@ Learn how to deploy Docker Desktop for Windows and Mac using Intune, Microsoft's
>
> This is because the Docker Desktop installer installs Windows features depending on your engine selection and also updates the membership of the `docker-users` local group.
>
> You may also want to set Intune to determine behaviour based on return codes and watch for a return code of `3010`.
> You may also want to set Intune to determine behaviour based on return codes and watch for a return code of `3010`. Return code 3010 means the installation succeeded but a reboot is required.
7. Complete the rest of the tabs and then review and create the app.
7. Complete the remaining tabs, then review and create the app.
{{< /tab >}}
{{< tab name="Mac" >}}
@ -39,7 +39,7 @@ Learn how to deploy Docker Desktop for Windows and Mac using Intune, Microsoft's
First, upload the package:
1. Sign in to your Intune admin center.
2. Add a new app. Select **Apps**, then **macOSs**, then **Add**.
2. Add a new app. Select **Apps**, then **macOS**, then **Add**.
3. Select **Line-of-business app** and then **Select**.
4. Upload the `Docker.pkg` file and fill in the required details.
@ -55,4 +55,4 @@ Next, assign the app:
## Additional resources
- [Explore the FAQs](faq.md).
- Learn how to [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users.
- Learn how to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users.

14
content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md
View File

@ -1,6 +1,6 @@
---
title: Use Jamf Pro
description: Use Jamf Pro to deploy Docker Desktop
title: Deploy with Jamf Pro
description: Use Jamf Pro to deploy Docker Desktop for Mac
keywords: jamf, mac, docker desktop, deploy, mdm, enterprise, administrator, pkg
tags: [admin]
weight: 40
@ -8,25 +8,25 @@ weight: 40
{{< summary-bar feature_name="Jamf Pro" >}}
Learn how to deploy Docker Desktop for Mac using Jamf Pro.
Learn how to deploy Docker Desktop for Mac using Jamf Pro, including uploading the installer and creating a deployment policy.
First, upload the package:
1. From the Jamf pro console, Navigate to **Computers** > **Management Settings** > **Computer Management** > **Packages**.
1. From the Jamf Pro console, navigate to **Computers** > **Management Settings** > **Computer Management** > **Packages**.
2. Select **New** to add a new package.
3. Upload the `Docker.pkg` file.
Next, create a policy for deployment:
1. Navigate to **Computers** > **Policies**.
2. Select **New**to create a new policy.
2. Select **New** to create a new policy.
3. Enter a name for the policy, for example "Deploy Docker Desktop".
4. Under the **Packages** tab, add the Docker package you uploaded.
5. Configure the scope to target the devices or device groups you want to install Docker on.
5. Configure the scope to target the devices or device groups on which you want to install Docker.
6. Save the policy and deploy.
For more information, see [Jamf Pro's official documentation](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Policies.html).
## Additional resources
- Learn how to [Enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users.
- Learn how to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users.

14
content/manuals/desktop/setup/install/linux/_index.md
View File

@ -16,7 +16,7 @@ aliases:
> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250
> employees OR more than $10 million USD in annual revenue) requires a [paid
> employees or more than $10 million USD in annual revenue) requires a [paid
> subscription](https://www.docker.com/pricing/).
This page contains information about general system requirements, supported platforms, and instructions on how to install Docker Desktop for Linux.
@ -27,11 +27,11 @@ This page contains information about general system requirements, supported plat
>
>This means images and containers deployed on the Linux Docker Engine (before installation) are not available in Docker Desktop for Linux.
>
> {{< accordion title=" What is the difference between Docker Desktop for Linux and Docker Engine?" >}}
> {{< accordion title=" Docker Desktop vs Docker Engine: What's the difference?" >}}
> [!IMPORTANT]
>
> For commercial use of Docker Engine obtained via Docker Desktop within larger enterprises (exceeding 250 employees OR with annual revenue surpassing $10 million USD), a [paid subscription](https://www.docker.com/pricing/) is required.
> For commercial use of Docker Engine obtained via Docker Desktop within larger enterprises (exceeding 250 employees or with annual revenue surpassing $10 million USD), a [paid subscription](https://www.docker.com/pricing/) is required.
Docker Desktop for Linux provides a user-friendly graphical interface that simplifies the management of containers and services. It includes Docker Engine as this is the core technology that powers Docker containers. Docker Desktop for Linux also comes with additional features like Docker Scout and Docker Extensions.
@ -82,7 +82,7 @@ Docker CLI commands target Docker Desktop. On shutdown, Docker Desktop resets
the current context to the `default` context.
Use the `docker context ls` command to view what contexts are available on your
machine. The current context is indicated with an asterisk (`*`);
machine. The current context is indicated with an asterisk (`*`).
```console
$ docker context ls
@ -114,7 +114,7 @@ Refer to the [Docker Context documentation](/manuals/engine/manage-resources/con
## Supported platforms
Docker provides `.deb` and `.rpm` packages from the following Linux distributions
Docker provides `.deb` and `.rpm` packages for the following Linux distributions
and architectures:
| Platform | x86_64 / amd64 |
@ -137,8 +137,8 @@ To install Docker Desktop successfully, your Linux host must meet the following
- 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 later. We recommend upgrading to the latest version.
- systemd init system.
- Gnome, KDE, or MATE Desktop environment.
- For many Linux distributions, the Gnome environment does not support tray icons. To add support for tray icons, you need to install a Gnome extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/).
- GNOME, KDE, or MATE desktop environment.
- For many Linux distributions, the GNOME environment does not support tray icons. To add support for tray icons, you need to install a GNOME extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/).
- At least 4 GB of RAM.
- Enable configuring ID mapping in user namespaces, see [File sharing](/manuals/desktop/troubleshoot-and-support/faqs/linuxfaqs.md#how-do-i-enable-file-sharing). Note that for Docker Desktop version 4.35 and later, this is not required anymore.
- Recommended: [Initialize `pass`](/manuals/desktop/setup/sign-in.md#credentials-management-for-linux-users) for credentials management.

4
content/manuals/desktop/setup/install/linux/archlinux.md
View File

@ -11,6 +11,8 @@ aliases:
- /desktop/install/linux/archlinux/
---
{{< summary-bar feature_name="Docker Desktop Archlinux" >}}
> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250
@ -19,7 +21,7 @@ aliases:
This page contains information on how to install, launch and upgrade Docker Desktop on an Arch-based distribution.
{{< summary-bar feature_name="Docker Desktop Archlinux" >}}
## Prerequisites

7
content/manuals/desktop/setup/install/linux/debian.md
View File

@ -27,8 +27,7 @@ To install Docker Desktop successfully, you must:
- Meet the [general system requirements](_index.md#general-system-requirements).
- Have a 64-bit version of Debian 12.
- For a Gnome Desktop environment, you must also install AppIndicator and KStatusNotifierItem [Gnome extensions](https://extensions.gnome.org/extension/615/appindicator-support/).
- For non-Gnome Desktop environments, `gnome-terminal` must be installed:
- If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:
```console
$ sudo apt install gnome-terminal
@ -43,7 +42,7 @@ Recommended approach to install Docker Desktop on Debian:
2. Download the latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). For checksums, see the [Release notes](/manuals/desktop/release-notes.md).
3. Install the package with apt as follows:
3. Install the package using `apt`:
```console
$ sudo apt-get update
@ -61,7 +60,7 @@ Recommended approach to install Docker Desktop on Debian:
By default, Docker Desktop is installed at `/opt/docker-desktop`.
There are a few post-install configuration steps done through the post-install script contained in the deb package.
The RPM package includes a post-install script that completes additional setup steps automatically.
The post-install script:

14
content/manuals/desktop/setup/install/linux/fedora.md
View File

@ -26,14 +26,12 @@ To install Docker Desktop successfully, you must:
- Meet the [general system requirements](_index.md#general-system-requirements).
- Have a 64-bit version of Fedora 40 or Fedora 41.
- For a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/).
- If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:
Additionally, for a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/).
For non-GNOME desktop environments, `gnome-terminal` must be installed:
```console
$ sudo dnf install gnome-terminal
```
```console
$ sudo dnf install gnome-terminal
```
## Install Docker Desktop
@ -51,7 +49,7 @@ To install Docker Desktop on Fedora:
By default, Docker Desktop is installed at `/opt/docker-desktop`.
There are a few post-install configuration steps done through the post-install script contained in the RPM package.
The RPM package includes a post-install script that completes additional setup steps automatically.
The post-install script:

70
content/manuals/desktop/setup/install/linux/rhel.md
View File

@ -6,11 +6,6 @@ keywords: red hat, red hat enterprise linux, rhel, rpm,
title: Install Docker Desktop on RHEL
linkTitle: RHEL
download-url-base: https://download.docker.com/linux/rhel
params:
sidebar:
badge:
color: green
text: New
aliases:
- /desktop/install/linux/rhel/
---
@ -18,7 +13,7 @@ aliases:
> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250
> employees OR more than $10 million USD in annual revenue) requires a [paid
> employees or more than $10 million USD in annual revenue) requires a [paid
> subscription](https://www.docker.com/pricing/).
This page contains information on how to install, launch and upgrade Docker Desktop on a Red Hat Enterprise Linux (RHEL) distribution.
@ -31,57 +26,54 @@ To install Docker Desktop successfully, you must:
- Have a 64-bit version of either RHEL 8 or RHEL 9.
- Have a [Docker account](/manuals/accounts/create-account.md), as authentication is required for Docker Desktop on RHEL.
If you don't have `pass` installed, or it can't be installed, you must enable
[CodeReady Linux Builder (CRB) repository](https://access.redhat.com/articles/4348511)
and
[Extra Packages for Enterprise Linux (EPEL)](https://docs.fedoraproject.org/en-US/epel/).
- If `pass` is not installed, or it can't be installed, you must enable [CodeReady Linux Builder (CRB) repository](https://access.redhat.com/articles/4348511) and [Extra Packages for Enterprise Linux (EPEL)](https://docs.fedoraproject.org/en-US/epel/).
{{< tabs group="os_version" >}}
{{< tab name="RHEL 9" >}}
```console
$ sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
$ sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
$ sudo dnf install pass
```
```console
$ sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
$ sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
$ sudo dnf install pass
```
{{< /tab >}}
{{< tab name="RHEL 8" >}}
```console
$ sudo subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms
$ sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
$ sudo dnf install pass
```
```console
$ sudo subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms
$ sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
$ sudo dnf install pass
```
{{< /tab >}}
{{< /tabs >}}
Additionally, for a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/). You must also enable EPEL.
- For a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/). You must also enable EPEL.
{{< tabs group="os_version" >}}
{{< tab name="RHEL 9" >}}
```console
$ # enable EPEL as described above
$ sudo dnf install gnome-shell-extension-appindicator
$ sudo gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
```
```console
$ # enable EPEL as described above
$ sudo dnf install gnome-shell-extension-appindicator
$ sudo gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
```
{{< /tab >}}
{{< tab name="RHEL 8" >}}
```console
$ # enable EPEL as described above
$ sudo dnf install gnome-shell-extension-appindicator
$ sudo dnf install gnome-shell-extension-desktop-icons
$ sudo gnome-shell-extension-tool -e appindicatorsupport@rgcjonas.gmail.com
```
```console
$ # enable EPEL as described above
$ sudo dnf install gnome-shell-extension-appindicator
$ sudo dnf install gnome-shell-extension-desktop-icons
$ sudo gnome-shell-extension-tool -e appindicatorsupport@rgcjonas.gmail.com
```
{{< /tab >}}
{{< /tabs >}}
For non-GNOME desktop environments, `gnome-terminal` must be installed:
- If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:
```console
$ sudo dnf install gnome-terminal
```
```console
$ sudo dnf install gnome-terminal
```
## Install Docker Desktop
@ -101,14 +93,14 @@ To install Docker Desktop on RHEL:
$ sudo dnf install ./docker-desktop-x86_64-rhel.rpm
```
There are a few post-install configuration steps done through the post-install script contained in the RPM package.
The RPM package includes a post-install script that completes additional setup steps automatically.
The post-install script:
- Sets the capability on the Docker Desktop binary to map privileged ports and set resource limits.
- Adds a DNS name for Kubernetes to `/etc/hosts`.
- Creates a symlink from `/usr/local/bin/com.docker.cli` to `/usr/bin/docker`.
This is because the classic Docker CLI is installed at `/usr/bin/docker`. The Docker Desktop installer also installs a Docker CLI binary that includes cloud-integration capabilities and is essentially a wrapper for the Compose CLI, at`/usr/local/bin/com.docker.cli`. The symlink ensures that the wrapper can access the classic Docker CLI.
This is because the classic Docker CLI is installed at `/usr/bin/docker`. The Docker Desktop installer also installs a Docker CLI binary that includes cloud-integration capabilities and is essentially a wrapper for the Compose CLI, at `/usr/local/bin/com.docker.cli`. The symlink ensures that the wrapper can access the classic Docker CLI.
- Creates a symlink from `/usr/libexec/qemu-kvm` to `/usr/local/bin/qemu-system-x86_64`.
## Launch Docker Desktop
@ -140,7 +132,7 @@ $ sudo dnf install ./docker-desktop-<arch>-rhel.rpm
## Next steps
- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you.
- Review [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you.
- Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application.
- [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features.
- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues.

18
content/manuals/desktop/setup/install/linux/ubuntu.md
View File

@ -1,5 +1,5 @@
---
description: Learn how to install, launch and upgrade Docker Desktop on Ubuntu. This
description: Learn how to install, launch, and upgrade Docker Desktop on Ubuntu. This
quick guide will cover prerequisites, installation methods, and more.
keywords: install docker ubuntu, ubuntu install docker, install docker on ubuntu,
docker install ubuntu, how to install docker on ubuntu, ubuntu docker install, docker
@ -18,7 +18,7 @@ aliases:
> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250
> employees OR more than $10 million USD in annual revenue) requires a [paid
> employees or more than $10 million USD in annual revenue) requires a [paid
> subscription](https://www.docker.com/pricing/).
This page contains information on how to install, launch and upgrade Docker Desktop on an Ubuntu distribution.
@ -29,7 +29,7 @@ To install Docker Desktop successfully, you must:
- Meet the [general system requirements](_index.md#general-system-requirements).
- Have an x86-64 system with Ubuntu 22.04, 24.04, or the latest non-LTS version.
- For non-Gnome Desktop environments, `gnome-terminal` must be installed:
- If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:
```console
$ sudo apt install gnome-terminal
```
@ -43,7 +43,7 @@ Recommended approach to install Docker Desktop on Ubuntu:
2. Download the latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). For checksums, see the [Release notes](/manuals/desktop/release-notes.md).
3. Install the package with apt as follows:
3. Install the package using `apt`:
```console
$ sudo apt-get update
@ -61,14 +61,14 @@ Recommended approach to install Docker Desktop on Ubuntu:
By default, Docker Desktop is installed at `/opt/docker-desktop`.
There are a few post-install configuration steps done through the post-install script contained in the deb package.
The DEB package includes a post-install script that completes additional setup steps automatically.
The post-install script:
- Sets the capability on the Docker Desktop binary to map privileged ports and set resource limits.
- Adds a DNS name for Kubernetes to `/etc/hosts`.
- Creates a symlink from `/usr/local/bin/com.docker.cli` to `/usr/bin/docker`.
This is because the classic Docker CLI is installed at `/usr/bin/docker`. The Docker Desktop installer also installs a Docker CLI binary that includes cloud-integration capabilities and is essentially a wrapper for the Compose CLI, at`/usr/local/bin/com.docker.cli`. The symlink ensures that the wrapper can access the classic Docker CLI.
This is because the classic Docker CLI is installed at `/usr/bin/docker`. The Docker Desktop installer also installs a Docker CLI binary that includes cloud-integration capabilities and is essentially a wrapper for the Compose CLI, at `/usr/local/bin/com.docker.cli`. The symlink ensures that the wrapper can access the classic Docker CLI.
## Launch Docker Desktop
@ -76,7 +76,7 @@ The post-install script:
## Upgrade Docker Desktop
Once a new version for Docker Desktop is released, the Docker UI shows a notification.
When a new version for Docker Desktop is released, the Docker UI shows a notification.
You need to download the new package each time you want to upgrade Docker Desktop and run:
```console
@ -85,8 +85,8 @@ $ sudo apt-get install ./docker-desktop-amd64.deb
## Next steps
- Explore [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you.
- Take a look at the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application.
- Review [Docker's subscriptions](https://www.docker.com/pricing/) to see what Docker can offer you.
- Follow the [Docker workshop](/get-started/workshop/_index.md) to learn how to build an image and run it as a containerized application.
- [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and all its features.
- [Troubleshooting](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) describes common problems, workarounds, how to run and submit diagnostics, and submit issues.
- [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md) provide answers to frequently asked questions.

24
content/manuals/desktop/setup/install/mac-install.md
View File

@ -1,5 +1,5 @@
---
description: Install Docker for Mac to get started. This guide covers system requirements,
description: Install Docker Desktop for Mac to get started. This guide covers system requirements,
where to download, and instructions on how to install and update.
keywords: docker for mac, install docker macos, docker mac, docker mac install, docker
install macos, install docker on mac, install docker macbook, docker desktop for
@ -21,10 +21,10 @@ aliases:
> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250
> employees OR more than $10 million USD in annual revenue) requires a [paid
> employees or more than $10 million USD in annual revenue) requires a [paid
> subscription](https://www.docker.com/pricing/).
This page contains download URLs, information about system requirements, and instructions on how to install Docker Desktop for Mac.
This page provides download links, system requirements, and step-by-step installation instructions for Docker Desktop on Mac.
{{< button text="Docker Desktop for Mac with Apple silicon" url="https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-arm64" >}}
{{< button text="Docker Desktop for Mac with Intel chip" url="https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-mac-amd64" >}}
@ -44,7 +44,7 @@ This page contains download URLs, information about system requirements, and ins
> [!IMPORTANT]
>
> Docker supports Docker Desktop on the most recent versions of macOS. That is, the current release of macOS and the previous two releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases).
> Docker Desktop is supported on the current and two previous major macOS releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases).
- At least 4 GB of RAM.
@ -55,10 +55,10 @@ This page contains download URLs, information about system requirements, and ins
> [!IMPORTANT]
>
> Docker supports Docker Desktop on the most recent versions of macOS. That is, the current release of macOS and the previous two releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases).
> Docker Desktop is supported on the current and two previous major macOS releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases).
- At least 4 GB of RAM.
- For the best experience, it's recommended that you install Rosetta 2. There is no longer a hard requirement to install Rosetta 2, however there are a few optional command line tools that still require Rosetta 2 when using Darwin/AMD64. See [Known issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). To install Rosetta 2 manually from the command line, run the following command:
- For the best experience, it's recommended that you install Rosetta 2. Rosetta 2 is no longer strictly required, however there are a few optional command line tools that still require Rosetta 2 when using Darwin/AMD64. See [Known issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md). To install Rosetta 2 manually from the command line, run the following command:
```console
$ softwareupdate --install-rosetta
@ -111,13 +111,25 @@ $ sudo hdiutil detach /Volumes/Docker
By default, Docker Desktop is installed at `/Applications/Docker.app`. As macOS typically performs security checks the first time an application is used, the `install` command can take several minutes to run.
#### Installer flags
The `install` command accepts the following flags:
##### Installation behavior
- `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run.
- `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI.
##### Security and access
- `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application
- `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI.
- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by administrators to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md).
- It must be used together with the `--allowed-org=<org name>` flag.
- For example: `--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"`
##### Proxy configuration
- `--proxy-http-mode=<mode>`: Sets the HTTP Proxy mode. The two modes are `system` (default) or `manual`.
- `--override-proxy-http=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests. It requires `--proxy-http-mode` to be `manual`.
- `--override-proxy-https=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests, requires `--proxy-http-mode` to be `manual`

94
content/manuals/desktop/setup/install/mac-permission-requirements.md
View File

@ -3,6 +3,7 @@ description: Understand permission requirements for Docker Desktop for Mac and t
differences between versions
keywords: Docker Desktop, mac, security, install, permissions
title: Understand permission requirements for Docker Desktop on Mac
linkTitle: Mac permission requirements
aliases:
- /docker-for-mac/privileged-helper/
- /desktop/mac/privileged-helper/
@ -15,20 +16,17 @@ This page contains information about the permission requirements for running and
It also provides clarity on running containers as `root` as opposed to having `root` access on the host.
Docker Desktop on Windows is designed with security in mind. Administrative rights are only required when absolutely necessary.
## Permission requirements
Docker Desktop for Mac is run as an unprivileged user. However, Docker Desktop requires certain functionalities 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 operating systems still prevent unprivileged processes from binding them which breaks commands like `docker run -p 127.0.0.1:80:80 docker/getting-started`.
- [Binding privileged ports](#binding-privileged-ports) that are less than 1024. Although privileged ports (ports below 1024) are not typically used as a security boundary, operating systems still prevent unprivileged processes from binding to 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 don't 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.
Depending on which version of Docker Desktop for Mac is used, privileged access is granted either during installation, first run, or only when it's needed.
{{< tabs >}}
{{< tab name="Version 4.18 and later" >}}
From version 4.18 and later, Docker Desktop for Mac provides greater control over functionality that's enabled during installation.
Privileged access is granted during installation.
The first time Docker Desktop for Mac launches, it presents an installation window where you can choose to either use the default settings, which work for most developers and requires you to grant privileged access, or use advanced settings.
@ -41,101 +39,29 @@ Depending on which advanced settings you configure, you must enter your password
You can change these configurations at a later date from the **Advanced** page in **Settings**.
{{< /tab >}}
{{< tab name="Version 4.15 - 4.17" >}}
Versions 4.15 to 4.17 of Docker Desktop for Mac don'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 aren't allowed by default on the host OS.
{{< /tab >}}
{{< tab name="Versions prior to 4.15" >}}
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 launches 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's 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`.
{{< /tab >}}
{{< /tabs >}}
### Installing symlinks
The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop creates symlinks for the binaries in `/usr/local/bin`, which means they're automatically included in `PATH` on most systems.
{{< tabs >}}
{{< tab name="Version 4.18 and later" >}}
You can choose whether to install symlinks either in `/usr/local/bin` or `$HOME/.docker/bin` during installation of Docker Desktop.
With version 4.18 and later, you can choose whether to install symlinks either in `/usr/local/bin` or `$HOME/.docker/bin` during installation of Docker Desktop.
If `/usr/local/bin` is chosen, and this location is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created in `/usr/local/bin`. If `$HOME/.docker/bin` is chosen, authorization is not required, but then you must [manually add `$HOME/.docker/bin`](/manuals/desktop/settings-and-maintenance/settings.md#advanced) to their PATH.
If `/usr/local/bin` is chosen, and this location is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created in `/usr/local/bin`. If `$HOME/.docker/bin` is chosen, authorization is not required, but then you must [manually add `$HOME/.docker/bin`](/manuals/desktop/settings-and-maintenance/settings.md#advanced) to your PATH.
You are also given the option to enable the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various Docker clients relying on the default Docker socket path work without additional changes.
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 you aren't prompted on each startup to create the symlink. If you don't enable this option at installation, the symlink and the startup task is not created and you 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.
{{< /tab >}}
{{< tab name="Version 4.17 and earlier" >}}
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 you 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 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 a 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 are 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.
{{< /tab >}}
{{< /tabs >}}
### Binding privileged ports
{{< tabs >}}
{{< tab name="Version 4.18 and later" >}}
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.
{{< /tab >}}
{{< tab name="Version 4.17 and earlier" >}}
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 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
docker: Error response from daemon: Ports are not available: exposing port
TCP 127.0.0.1:80 -> 0.0.0.0:0: failed to connect to /var/run/com.docker.vmnetd.sock:
is vmnetd running?: dial unix /var/run/com.docker.vmnetd.sock: connect: connection
refused.
ERRO[0003] error waiting for container: context canceled
```
> [!NOTE]
>
> 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.
{{< /tab >}}
{{< /tabs >}}
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.
### Ensuring `localhost` and `kubernetes.docker.internal` are defined
{{< tabs >}}
{{< tab name="Version 4.18 and later" >}}
With versions 4.18 and later, 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`.
{{< /tab >}}
{{< tab name="Version 4.17 and earlier" >}}
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.
{{< /tab >}}
{{< /tabs >}}
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`.
## Installing from the command line
In version 4.11 and later of Docker Desktop for Mac, privileged configurations are applied during the installation with the `--user` flag on the [install command](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line). In this case, you are not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag:
Privileged configurations are applied during the installation with the `--user` flag on the [install command](/manuals/desktop/setup/install/mac-install.md#install-from-the-command-line). In this case, you are not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag:
- Uninstalls the previous `com.docker.vmnetd` if present
- Sets up symlinks
- Ensures that `localhost` is resolved to `127.0.0.1`

61
content/manuals/desktop/setup/install/windows-install.md
View File

@ -28,7 +28,7 @@ aliases:
> employees OR more than $10 million USD in annual revenue) requires a [paid
> subscription](https://www.docker.com/pricing/).
This page contains the download URL, information about system requirements, and instructions on how to install Docker Desktop for Windows.
This page provides download links, system requirements, and step-by-step installation instructions for Docker Desktop on Windows.
{{< button text="Docker Desktop for Windows - x86_64" url="https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-amd64" >}}
{{< button text="Docker Desktop for Windows - Arm (Beta)" url="https://desktop.docker.com/win/main/arm64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-win-arm64" >}}
@ -41,7 +41,7 @@ _For checksums, see [Release notes](/manuals/desktop/release-notes.md)_
>
> **Should I use Hyper-V or WSL?**
>
> Docker Desktop's functionality remains consistent on both WSL and Hyper-V, without a preference for either architecture. Hyper-V and WSL have their own advantages and disadvantages, depending on your specific set up and your planned use case.
> Docker Desktop's functionality remains consistent on both WSL and Hyper-V, without a preference for either architecture. Hyper-V and WSL have their own advantages and disadvantages, depending on your specific setup and your planned use case.
{{< tabs >}}
{{< tab name="WSL 2 backend, x86_64" >}}
@ -171,9 +171,9 @@ again when you switch back.
3. When prompted, ensure the **Use WSL 2 instead of Hyper-V** option on the Configuration page is selected or not depending on your choice of backend.
If your system only supports one of the two options, you won't be able to select which backend to use.
On systems that support only one backend, Docker Desktop automatically selects the available option.
4. Follow the instructions on the installation wizard to authorize the installer and proceed with the install.
4. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation.
5. When the installation is successful, select **Close** to complete the installation process.
@ -207,26 +207,7 @@ start /w "" "Docker Desktop Installer.exe" install
By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`.
The `install` command accepts the following flags:
- `--quiet`: Suppresses information output when running the installer
- `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run
- `--no-windows-containers`: Disables the Windows containers integration. This can improve security. For more information, see [Windows containers](/manuals/desktop/setup/install/windows-permission-requirements.md#windows-containers).
- `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application
- `--backend=<backend name>`: Selects the default backend to use for Docker Desktop, `hyper-v`, `windows` or `wsl-2` (default)
- `--installation-dir=<path>`: Changes the default installation location (`C:\Program Files\Docker\Docker`)
- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md).
- It must be used together with the `--allowed-org=<org name>` flag.
- For example:`--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"`
- `--proxy-http-mode=<mode>`: Sets the HTTP Proxy mode, `system` (default) or `manual`
- `--override-proxy-http=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests, requires `--proxy-http-mode` to be `manual`
- `--override-proxy-https=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests, requires `--proxy-http-mode` to be `manual`
- `--override-proxy-exclude=<hosts/domains>`: Bypasses proxy settings for the hosts and domains. Uses a comma-separated list.
- `--proxy-enable-kerberosntlm`: Enables Kerberos and NTLM proxy authentication. If you are enabling this, ensure your proxy server is properly configured for Kerberos/NTLM authentication. Available with Docker Desktop 4.32 and later.
- `--hyper-v-default-data-root=<path>`: Specifies the default location for the Hyper-V VM disk.
- `--windows-containers-default-data-root=<path>`: Specifies the default location for the Windows containers.
- `--wsl-default-data-root=<path>`: Specifies the default location for the WSL distribution disk.
- `--always-run-service`: After installation completes, starts `com.docker.service` and sets the service startup type to Automatic. This circumvents the need for administrator privileges, which are otherwise necessary to start `com.docker.service`. `com.docker.service` is required by Windows containers and Hyper-V backend.
#### Installer flags
> [!NOTE]
>
@ -242,6 +223,38 @@ If your admin account is different to your user account, you must add the user t
$ net localgroup docker-users <user> /add
```
The `install` command accepts the following flags:
##### Installation behavior
- `--quiet`: Suppresses information output when running the installer
- `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run
- `--installation-dir=<path>`: Changes the default installation location (`C:\Program Files\Docker\Docker`)
- `--backend=<backend name>`: Selects the default backend to use for Docker Desktop, `hyper-v`, `windows` or `wsl-2` (default)
- `--always-run-service`: After installation completes, starts `com.docker.service` and sets the service startup type to Automatic. This circumvents the need for administrator privileges, which are otherwise necessary to start `com.docker.service`. `com.docker.service` is required by Windows containers and Hyper-V backend.
##### Security and access control
- `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application
- `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md).
- It must be used together with the `--allowed-org=<org name>` flag.
- For example:`--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"`
- `--no-windows-containers`: Disables the Windows containers integration. This can improve security. For more information, see [Windows containers](/manuals/desktop/setup/install/windows-permission-requirements.md#windows-containers).
##### Proxy configuration
- `--proxy-http-mode=<mode>`: Sets the HTTP Proxy mode, `system` (default) or `manual`
- `--override-proxy-http=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests, requires `--proxy-http-mode` to be `manual`
- `--override-proxy-https=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests, requires `--proxy-http-mode` to be `manual`
- `--override-proxy-exclude=<hosts/domains>`: Bypasses proxy settings for the hosts and domains. Uses a comma-separated list.
- `--proxy-enable-kerberosntlm`: Enables Kerberos and NTLM proxy authentication. If you are enabling this, ensure your proxy server is properly configured for Kerberos/NTLM authentication. Available with Docker Desktop 4.32 and later.
##### Data root and disk location
- `--hyper-v-default-data-root=<path>`: Specifies the default location for the Hyper-V VM disk.
- `--windows-containers-default-data-root=<path>`: Specifies the default location for the Windows containers.
- `--wsl-default-data-root=<path>`: Specifies the default location for the WSL distribution disk.
## Start Docker Desktop
Docker Desktop does not start automatically after installation. To start Docker Desktop:

14
content/manuals/desktop/setup/install/windows-permission-requirements.md
View File

@ -2,6 +2,7 @@
description: Understand permission requirements for Docker Desktop for Windows
keywords: Docker Desktop, Windows, security, install
title: Understand permission requirements for Windows
linkTitle: Windows permission requirements
aliases:
- /desktop/windows/privileged-helper/
- /desktop/windows/permission-requirements/
@ -9,10 +10,12 @@ aliases:
weight: 40
---
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.
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.
Docker Desktop on Windows is designed with security in mind. Administrative rights are only required when absolutely necessary.
## Permission requirements
While Docker Desktop on Windows can be run without having `Administrator` privileges, it does require them during installation. On installation you receive a UAC prompt which allows a privileged helper service to be installed. After that, Docker Desktop can be run without administrator privileges, provided you are members of the `docker-users` group. If you performed the installation, you are automatically added to this group, but other users must be added manually. This allows the administrator to control who has access to Docker Desktop.
@ -27,7 +30,7 @@ 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.
- Ensuring that `host.docker.internal` and `gateway.docker.internal` are defined in the Win32 hosts file. They point to the host local IP address and allow an application to resolve the host IP using the same name from either the host itself or a container.
- 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.
- 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.
- Moving the VHDX file or folder.
- Starting and stopping the Windows Docker engine and querying whether it's running.
- Deleting all Windows containers data files.
@ -38,7 +41,7 @@ The service performs the following functionalities:
The service start mode depends on which container engine is selected, and, for WSL, on whether it is needed to maintain `host.docker.internal` and `gateway.docker.internal` in the Win32 hosts file. This is controlled by a setting under `Use the WSL 2 based engine` in the settings page. When this is set, WSL engine behaves the same as Hyper-V. So:
- 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 so you can launch Docker Desktop without admin privileges.
- With WSL2 Linux containers, the service isn't necessary and therefore doesn't run automatically when the system boots. When you switch to Windows containers or Hyper-V Linux containers, or choose to maintain `host.docker.internal` and `gateway.docker.internal` in the Win32 hosts file, a UAC prompt is displayed which asks you 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.
- With WSL2 Linux containers, the service isn't necessary and therefore doesn't run automatically when the system boots. When you switch to Windows containers or Hyper-V Linux containers, or choose to maintain `host.docker.internal` and `gateway.docker.internal` in the Win32 hosts file, a UAC prompt appears asking you 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
@ -49,8 +52,7 @@ installed software. This means that although containers run by default as
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
you access to any files that it doesn’t already have access to.
into Docker containers still retain their original permissions. Containers don't have access to any host files beyond those explicitly shared.
## Enhanced Container Isolation
@ -65,7 +67,7 @@ Desktop VM. ECI uses this and other advanced techniques to further secure
containers within the Docker Desktop Linux VM, such that they are further
isolated from the Docker daemon and other services running inside the VM.
## Windows Containers
## Windows containers
> [!WARNING]
>

69
content/manuals/desktop/setup/sign-in.md
View File

@ -30,7 +30,7 @@ aliases:
- /desktop/get-started/
---
Docker recommends that you authenticate using the **Sign in** option in the top-right corner of the Docker Dashboard.
Docker recommends signing in with the **Sign in** option in the top-right corner of the Docker Dashboard.
In large enterprises where admin access is restricted, administrators can [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md).
@ -40,11 +40,11 @@ In large enterprises where admin access is restricted, administrators can [enfor
## Benefits of signing in
- You can access your Docker Hub repositories directly from Docker Desktop.
- Access your Docker Hub repositories directly from Docker Desktop.
- Authenticated users also get a higher pull rate limit compared to anonymous users. For more information, see [Usage and limits](/manuals/docker-hub/usage/_index.md).
- Increase your pull rate limit compared to anonymous users. See [Usage and limits](/manuals/docker-hub/usage/_index.md).
- Improve your organization’s security posture for containerized development by taking advantage of [Hardened Desktop](/manuals/security/for-admins/hardened-desktop/_index.md).
- Enhance your organization’s security posture for containerized development with [Hardened Desktop](/manuals/security/for-admins/hardened-desktop/_index.md).
> [!NOTE]
>
@ -52,49 +52,40 @@ In large enterprises where admin access is restricted, administrators can [enfor
## Signing in with Docker Desktop for Linux
Docker Desktop for Linux relies on [`pass`](https://www.passwordstore.org/) to store credentials in gpg2-encrypted files.
Docker Desktop for Linux relies on [`pass`](https://www.passwordstore.org/) to store credentials in GPG-encrypted files.
Before signing in to Docker Desktop with your [Docker ID](/accounts/create-account/), you must initialize `pass`.
Docker Desktop displays a warning if you've not initialized `pass`.
Docker Desktop displays a warning if `pass` is not configured.
You can initialize pass by using a gpg key. To generate a gpg key, run:
1. Generate a GPG key. You can initialize pass by using a gpg key. To generate a gpg key, run:
``` console
$ gpg --generate-key
```
``` console
$ gpg --generate-key
```
2. Enter your name and email once prompted.
The following is an example similar to what you see once you run the previous command:
Once confirmed, GPG creates a key pair. Look for the `pub` line that contains your GPG ID, for example:
```console {hl_lines=12}
...
GnuPG needs to construct a user ID to identify your key.
```text
...
pubrsa3072 2022-03-31 [SC] [expires: 2024-03-30]
3ABCD1234EF56G78
uid Molly <molly@example.com>
```
3. Copy the GPG ID and use it to initialize `pass`
Real name: Molly
Email address: molly@example.com
You selected this USER-ID:
"Molly <molly@example.com>"
```console
$ pass init <your_generated_gpg-id_public_key>
```
Change (N)ame, (E)mail, or (O)kay/(Q)uit? O
...
pubrsa3072 2022-03-31 [SC] [expires: 2024-03-30]
<generated gpg-id public key>
uid Molly <molly@example.com>
subrsa3072 2022-03-31 [E] [expires: 2024-03-30]
```
You should see output similar to:
To initialize `pass`, run the following command using the public key generated from the previous command:
```console
$ pass init <your_generated_gpg-id_public_key>
```
The following is an example similar to what you see once you run the previous command:
```console
mkdir: created directory '/home/molly/.password-store/'
Password store initialized for <generated_gpg-id_public_key>
```
```text
mkdir: created directory '/home/molly/.password-store/'
Password store initialized for <generated_gpg-id_public_key>
```
Once you initialize `pass`, you can sign in and pull your private images.
When Docker CLI or Docker Desktop use credentials, a user prompt may pop up for the password you set during the gpg key generation.
When Docker CLI or Docker Desktop use credentials, a user prompt may pop up for the password you set during the GPG key generation.
```console
$ docker pull molly/privateimage
@ -109,5 +100,5 @@ docker.io/molly/privateimage:latest
## What's next?
- [Explore Docker Desktop](/manuals/desktop/use-desktop/_index.md) and its features.
- Change your Docker Desktop settings
- [Browse common FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md)
- Change your [Docker Desktop settings](/manuals/desktop/settings-and-maintenance/settings.md).
- [Browse common FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md).

18
content/manuals/desktop/setup/vm-vdi.md
View File

@ -2,13 +2,14 @@
description: Instructions on how to enable nested virtualization
keywords: nested virtualization, Docker Desktop, windows, VM, VDI environment
title: Run Docker Desktop for Windows in a VM or VDI environment
linkTitle: VM or VDI environments
aliases:
- /desktop/nested-virtualization/
- /desktop/vm-vdi/
weight: 30
---
In general, we recommend running Docker Desktop natively on either Mac, Linux, or Windows. However, Docker Desktop for Windows can run inside a virtual desktop provided the virtual desktop is properly configured.
Docker recommends running Docker Desktop natively on Mac, Linux, or Windows. However, Docker Desktop for Windows can run inside a virtual desktop provided the virtual desktop is properly configured.
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.
@ -18,11 +19,11 @@ To run Docker Desktop in a virtual desktop environment, it is essential nested v
>
> Support for running Docker Desktop on a virtual desktop is available to Docker Business customers, on VMware ESXi or Azure VMs only.
The support available from Docker extends to installing and running Docker Desktop inside the VM, once the nested virtualization is set up correctly. The only hypervisors we have successfully tested are VMware ESXi and Azure, and there is no support for other VMs. For more information on Docker Desktop support, see [Get support](/manuals/desktop/troubleshoot-and-support/support.md).
Docker support includes installing and running Docker Desktop within the VM, provided that nested virtualization is correctly enabled. The only hypervisors successfully tested are VMware ESXi and Azure, and there is no support for other VMs. For more information on Docker Desktop support, see [Get support](/manuals/desktop/troubleshoot-and-support/support.md).
For troubleshooting problems and intermittent failures that are outside of Docker's control, you should contact your hypervisor vendor. Each hypervisor vendor offers different levels of support. For example, Microsoft supports running nested Hyper-V both on-prem and on Azure, with some version constraints. This may not be the case for VMWare ESXi.
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.
Docker does not support running multiples instances of Docker Desktop on the same machine in a VM or VDI environment.
Docker does not support running multiple instances of Docker Desktop on the same machine in a VM or VDI environment.
## Turn on nested virtualization
@ -30,16 +31,15 @@ You must turn on nested virtualization before you install Docker Desktop on a vi
### Turn on nested virtualization on VMware ESXi
Nested virtualization of other hypervisors like Hyper-V inside a vSphere VM [is not a supported scenario](https://kb.vmware.com/s/article/2009916). However, running Hyper-V VM in a VMware ESXi VM is technically possible and, depending on the version, ESXi includes hardware-assisted virtualization as a supported feature. For internal testing, we used a VM that had 1 CPU with 4 cores and 12GB of memory.
Nested virtualization of other hypervisors like Hyper-V inside a vSphere VM [is not a supported scenario](https://kb.vmware.com/s/article/2009916). However, running Hyper-V VM in a VMware ESXi VM is technically possible and, depending on the version, ESXi includes hardware-assisted virtualization as a supported feature. A VM that had 1 CPU with 4 cores and 12GB of memory was used for internal testing.
For steps on how to expose hardware-assisted virtualization to the guest OS, [see VMware's documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-2A98801C-68E8-47AF-99ED-00C63E4857F6.html).
### Turn on nested virtualization on an Azure Virtual Machine
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 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. D4s_v5 machines were used for internal testing. Use this specification or above for optimal performance of Docker Desktop.
## Docker Desktop support on Nutanix-powered VDI
@ -57,6 +57,4 @@ Docker Desktop follows the VDI support definitions outlined [previously](#virtua
### Support scope and responsibilities
If WSL 2 encounters issues - for example, it crashes, fails to start, or experiences performance degradation - contact Nutanix support.
If Docker Desktop itself encounters issues, contact Docker support.
For WSL 2-related issues, contact Nutanix support. For Docker Desktop-specific issues, contact Docker support.