From 9696b3881a98472205bdbffb566dd7494153cbd6 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 2 Apr 2025 12:07:15 +0100 Subject: [PATCH 1/5] ENGDOCS-2515 --- content/manuals/desktop/_index.md | 18 ++-- .../install/enterprise-deployment/faq.md | 15 ++- .../msi-install-and-configure.md | 20 ++-- .../pkg-install-and-configure.md | 18 ++-- .../enterprise-deployment/use-intune.md | 14 +-- .../enterprise-deployment/use-jamf-pro.md | 14 +-- .../desktop/setup/install/linux/_index.md | 14 +-- .../desktop/setup/install/linux/debian.md | 7 +- .../desktop/setup/install/linux/fedora.md | 14 ++- .../desktop/setup/install/linux/rhel.md | 65 ++++++------- .../desktop/setup/install/linux/ubuntu.md | 18 ++-- .../desktop/setup/install/mac-install.md | 24 +++-- .../install/mac-permission-requirements.md | 94 ++----------------- .../desktop/setup/install/windows-install.md | 57 ++++++----- .../windows-permission-requirements.md | 14 +-- 15 files changed, 180 insertions(+), 226 deletions(-) diff --git a/content/manuals/desktop/_index.md b/content/manuals/desktop/_index.md index 17c87b9cfcd5..e80516b8c20a 100644 --- a/content/manuals/desktop/_index.md +++ b/content/manuals/desktop/_index.md @@ -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,6 +50,8 @@ 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?" >}} @@ -58,8 +59,9 @@ Docker Desktop reduces the time spent on complex setups so you can focus on writ - Docker CLI client - [Docker Scout](../scout/_index.md) (additional subscription may apply) - [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/) diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/faq.md b/content/manuals/desktop/setup/install/enterprise-deployment/faq.md index 979485823707..9d3ad95b9b01 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/faq.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/faq.md @@ -1,8 +1,9 @@ --- 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] +tags: [FAQ, admin,] aliases: - /desktop/install/msi/faq/ - /desktop/setup/install/msi/faq/ @@ -10,11 +11,15 @@ aliases: ## MSI +Common questions about installing Docker Desktop using the MSI package. + ### 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. + +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 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. +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: diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md index 2c783f5a862a..5ba0877bb244 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md @@ -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 engine: 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 as its value: > > - 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 diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md b/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md index 777d2f774789..b454ac0147e2 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md @@ -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. \ No newline at end of file diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md b/content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md index 721b60359d5d..7c3a137ebdea 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/use-intune.md @@ -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. \ No newline at end of file +- Learn how to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users. \ No newline at end of file diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md b/content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md index b0f2d03a9d58..7443d259afa0 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/use-jamf-pro.md @@ -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. \ No newline at end of file +- Learn how to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) for your users. \ No newline at end of file diff --git a/content/manuals/desktop/setup/install/linux/_index.md b/content/manuals/desktop/setup/install/linux/_index.md index 5cd8e9f3ab98..ac1d233d288b 100644 --- a/content/manuals/desktop/setup/install/linux/_index.md +++ b/content/manuals/desktop/setup/install/linux/_index.md @@ -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/). +- GNOW, 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. diff --git a/content/manuals/desktop/setup/install/linux/debian.md b/content/manuals/desktop/setup/install/linux/debian.md index c18bfbfac204..7938ea07b775 100644 --- a/content/manuals/desktop/setup/install/linux/debian.md +++ b/content/manuals/desktop/setup/install/linux/debian.md @@ -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: diff --git a/content/manuals/desktop/setup/install/linux/fedora.md b/content/manuals/desktop/setup/install/linux/fedora.md index 67303683eb7b..a084704d7e64 100644 --- a/content/manuals/desktop/setup/install/linux/fedora.md +++ b/content/manuals/desktop/setup/install/linux/fedora.md @@ -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. +- Additionally, 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: diff --git a/content/manuals/desktop/setup/install/linux/rhel.md b/content/manuals/desktop/setup/install/linux/rhel.md index d0c2eabf6007..1a9fb0c54c49 100644 --- a/content/manuals/desktop/setup/install/linux/rhel.md +++ b/content/manuals/desktop/setup/install/linux/rhel.md @@ -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 a Red Hat Enterprise Linux (RHEL) distribution. @@ -31,57 +31,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. +- 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. {{< 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 +98,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 +137,7 @@ $ sudo dnf install ./docker-desktop--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. diff --git a/content/manuals/desktop/setup/install/linux/ubuntu.md b/content/manuals/desktop/setup/install/linux/ubuntu.md index 43cc7e7e09cc..282bb8d81849 100644 --- a/content/manuals/desktop/setup/install/linux/ubuntu.md +++ b/content/manuals/desktop/setup/install/linux/ubuntu.md @@ -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. diff --git a/content/manuals/desktop/setup/install/mac-install.md b/content/manuals/desktop/setup/install/mac-install.md index 6228a93becc7..41940a299552 100644 --- a/content/manuals/desktop/setup/install/mac-install.md +++ b/content/manuals/desktop/setup/install/mac-install.md @@ -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=`: 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=`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application - `--user=`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](/manuals/desktop/setup/install/mac-permission-requirements.md#permission-requirements). To find the username, enter `ls /Users` in the CLI. - `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by administrators to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md). - It must be used together with the `--allowed-org=` flag. - For example: `--allowed-org= --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"` + +##### Proxy configuration + - `--proxy-http-mode=`: Sets the HTTP Proxy mode. The two modes are `system` (default) or `manual`. - `--override-proxy-http=`: 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=`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests, requires `--proxy-http-mode` to be `manual` diff --git a/content/manuals/desktop/setup/install/mac-permission-requirements.md b/content/manuals/desktop/setup/install/mac-permission-requirements.md index 9f24fe9d1ca7..0a9d458bc18b 100644 --- a/content/manuals/desktop/setup/install/mac-permission-requirements.md +++ b/content/manuals/desktop/setup/install/mac-permission-requirements.md @@ -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" >}} - -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. +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//.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//.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//.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//.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` diff --git a/content/manuals/desktop/setup/install/windows-install.md b/content/manuals/desktop/setup/install/windows-install.md index 91e432258231..7a19b8fe8bb8 100644 --- a/content/manuals/desktop/setup/install/windows-install.md +++ b/content/manuals/desktop/setup/install/windows-install.md @@ -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,40 +207,53 @@ start /w "" "Docker Desktop Installer.exe" install By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`. +#### Installer flags + +> [!NOTE] +> +> If you're using PowerShell, you need to use the `ArgumentList` parameter before any flags. +> For example: +> ```powershell +> Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--accept-license' +> ``` + +If your admin account is different to your user account, you must add the user to the **docker-users** group: + +```console +$ net localgroup docker-users /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 -- `--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=`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application -- `--backend=`: Selects the default backend to use for Docker Desktop, `hyper-v`, `windows` or `wsl-2` (default) - `--installation-dir=`: Changes the default installation location (`C:\Program Files\Docker\Docker`) +- `--backend=`: 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=`: 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=` flag. - For example:`--allowed-org= --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=`: Sets the HTTP Proxy mode, `system` (default) or `manual` - `--override-proxy-http=`: 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=`: 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=`: 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=`: Specifies the default location for the Hyper-V VM disk. - `--windows-containers-default-data-root=`: Specifies the default location for the Windows containers. - `--wsl-default-data-root=`: 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. - -> [!NOTE] -> -> If you're using PowerShell, you need to use the `ArgumentList` parameter before any flags. -> For example: -> ```powershell -> Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--accept-license' -> ``` - -If your admin account is different to your user account, you must add the user to the **docker-users** group: - -```console -$ net localgroup docker-users /add -``` ## Start Docker Desktop diff --git a/content/manuals/desktop/setup/install/windows-permission-requirements.md b/content/manuals/desktop/setup/install/windows-permission-requirements.md index 32917e4210ac..9ae094f312e6 100644 --- a/content/manuals/desktop/setup/install/windows-permission-requirements.md +++ b/content/manuals/desktop/setup/install/windows-permission-requirements.md @@ -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] > From 8471ec536446cd80e6b6c751670b7b12655982a5 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 2 Apr 2025 13:17:29 +0100 Subject: [PATCH 2/5] more edits --- _vale/Docker/Acronyms.yml | 3 + content/manuals/desktop/_index.md | 6 -- .../pkg-install-and-configure.md | 2 +- .../desktop/setup/install/linux/_index.md | 2 +- .../desktop/setup/install/linux/rhel.md | 5 -- content/manuals/desktop/setup/sign-in.md | 68 ++++++++----------- content/manuals/desktop/setup/vm-vdi.md | 18 +++-- 7 files changed, 43 insertions(+), 61 deletions(-) diff --git a/_vale/Docker/Acronyms.yml b/_vale/Docker/Acronyms.yml index 1117c8f56b62..b1dc301aa2ee 100644 --- a/_vale/Docker/Acronyms.yml +++ b/_vale/Docker/Acronyms.yml @@ -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 diff --git a/content/manuals/desktop/_index.md b/content/manuals/desktop/_index.md index e80516b8c20a..24ff0df7fcef 100644 --- a/content/manuals/desktop/_index.md +++ b/content/manuals/desktop/_index.md @@ -80,10 +80,4 @@ Docker Desktop integrates with your preferred development tools and languages, a {{< /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 >}} diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md b/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md index b454ac0147e2..94f0ec00e16a 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/pkg-install-and-configure.md @@ -26,7 +26,7 @@ The PKG package supports various MDM (Mobile Device Management) solutions, makin > [!NOTE] > -> 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. +> 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**. > diff --git a/content/manuals/desktop/setup/install/linux/_index.md b/content/manuals/desktop/setup/install/linux/_index.md index ac1d233d288b..f034da1a6e1f 100644 --- a/content/manuals/desktop/setup/install/linux/_index.md +++ b/content/manuals/desktop/setup/install/linux/_index.md @@ -137,7 +137,7 @@ 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. -- GNOW, KDE, or MATE desktop environment. +- 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. diff --git a/content/manuals/desktop/setup/install/linux/rhel.md b/content/manuals/desktop/setup/install/linux/rhel.md index 1a9fb0c54c49..2c8b7a66a5fb 100644 --- a/content/manuals/desktop/setup/install/linux/rhel.md +++ b/content/manuals/desktop/setup/install/linux/rhel.md @@ -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/ --- diff --git a/content/manuals/desktop/setup/sign-in.md b/content/manuals/desktop/setup/sign-in.md index 72ac850af5ce..aaf0384a9d0e 100644 --- a/content/manuals/desktop/setup/sign-in.md +++ b/content/manuals/desktop/setup/sign-in.md @@ -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,41 @@ 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. +1. Generate a GPG key. Run: 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 + ``` +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 " + ```console + $ pass init + ``` -Change (N)ame, (E)mail, or (O)kay/(Q)uit? O -... -pubrsa3072 2022-03-31 [SC] [expires: 2024-03-30] - -uid Molly -subrsa3072 2022-03-31 [E] [expires: 2024-03-30] -``` - -To initialize `pass`, run the following command using the public key generated from the previous command: - -```console -$ pass init -``` -The following is an example similar to what you see once you run the previous command: + You should see output similar to: -```console -mkdir: created directory '/home/molly/.password-store/' -Password store initialized for -``` + ```text + mkdir: created directory '/home/molly/.password-store/' + Password store initialized for + ``` 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 +101,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). diff --git a/content/manuals/desktop/setup/vm-vdi.md b/content/manuals/desktop/setup/vm-vdi.md index 37ade577b48f..153c1d9bff35 100644 --- a/content/manuals/desktop/setup/vm-vdi.md +++ b/content/manuals/desktop/setup/vm-vdi.md @@ -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. From 6263653d4235421d022febdd9699af05ce6c11cc Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 2 Apr 2025 13:23:32 +0100 Subject: [PATCH 3/5] more edits --- content/manuals/desktop/setup/install/linux/archlinux.md | 4 +++- content/manuals/desktop/setup/install/linux/fedora.md | 2 +- content/manuals/desktop/setup/install/linux/rhel.md | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/manuals/desktop/setup/install/linux/archlinux.md b/content/manuals/desktop/setup/install/linux/archlinux.md index 6a6c03bf5f9b..06ea014d235e 100644 --- a/content/manuals/desktop/setup/install/linux/archlinux.md +++ b/content/manuals/desktop/setup/install/linux/archlinux.md @@ -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 diff --git a/content/manuals/desktop/setup/install/linux/fedora.md b/content/manuals/desktop/setup/install/linux/fedora.md index a084704d7e64..4148069837ff 100644 --- a/content/manuals/desktop/setup/install/linux/fedora.md +++ b/content/manuals/desktop/setup/install/linux/fedora.md @@ -26,7 +26,7 @@ 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. -- Additionally, for a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/). +- 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: ```console diff --git a/content/manuals/desktop/setup/install/linux/rhel.md b/content/manuals/desktop/setup/install/linux/rhel.md index 2c8b7a66a5fb..88f0ae7aad74 100644 --- a/content/manuals/desktop/setup/install/linux/rhel.md +++ b/content/manuals/desktop/setup/install/linux/rhel.md @@ -47,7 +47,7 @@ To install Docker Desktop successfully, you must: {{< /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" >}} From 1caad5fe63ea034bdc0a2723b5306695cf8ea582 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 2 Apr 2025 13:27:20 +0100 Subject: [PATCH 4/5] more edits --- .../desktop/setup/install/enterprise-deployment/faq.md | 4 ++-- .../enterprise-deployment/msi-install-and-configure.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/faq.md b/content/manuals/desktop/setup/install/enterprise-deployment/faq.md index 9d3ad95b9b01..71e689bab4d2 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/faq.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/faq.md @@ -3,7 +3,7 @@ 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,] +tags: [FAQ, admin] aliases: - /desktop/install/msi/faq/ - /desktop/setup/install/msi/faq/ @@ -11,7 +11,7 @@ aliases: ## MSI -Common questions about installing Docker Desktop using the MSI package. +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`)? diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md index 5ba0877bb244..723b5aec8e26 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md @@ -30,7 +30,7 @@ The MSI package supports various MDM (Mobile Device Management) solutions, makin - Disable Windows Container usage - - Select the Docker Desktop engine: WSL or Hyper-V. If only one is supported by your system, you won't be able to choose. + - 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. From 77c79d58d8d34425a9bac6e8a635c9647d634227 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Wed, 2 Apr 2025 15:57:22 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Sarah Sanders --- content/manuals/desktop/_index.md | 2 +- .../enterprise-deployment/msi-install-and-configure.md | 2 +- content/manuals/desktop/setup/sign-in.md | 5 ++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/content/manuals/desktop/_index.md b/content/manuals/desktop/_index.md index 24ff0df7fcef..2a9c655f586a 100644 --- a/content/manuals/desktop/_index.md +++ b/content/manuals/desktop/_index.md @@ -57,7 +57,7 @@ Docker Desktop integrates with your preferred development tools and languages, a - [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 Compose](/manuals/compose/_index.md) - [Ask Gordon](/manuals/desktop/features/gordon/_index.md) diff --git a/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md index 723b5aec8e26..48750fc0845a 100644 --- a/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md +++ b/content/manuals/desktop/setup/install/enterprise-deployment/msi-install-and-configure.md @@ -116,7 +116,7 @@ msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /passive /norestart > [!TIP] > -> When creating a value that expects a JSON string as its 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 diff --git a/content/manuals/desktop/setup/sign-in.md b/content/manuals/desktop/setup/sign-in.md index aaf0384a9d0e..d05abf62592d 100644 --- a/content/manuals/desktop/setup/sign-in.md +++ b/content/manuals/desktop/setup/sign-in.md @@ -56,8 +56,7 @@ Docker Desktop for Linux relies on [`pass`](https://www.passwordstore.org/) to s Before signing in to Docker Desktop with your [Docker ID](/accounts/create-account/), you must initialize `pass`. Docker Desktop displays a warning if `pass` is not configured. -1. Generate a GPG key. Run: -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 @@ -72,7 +71,7 @@ You can initialize pass by using a gpg key. To generate a gpg key, run: 3ABCD1234EF56G78 uid Molly ``` -3.Copy the GPG ID and use it to initialize `pass` +3. Copy the GPG ID and use it to initialize `pass` ```console $ pass init