Engdocs 3223 (#24597)

<!--Delete sections as needed -->

## Description

New Windows.exe installation behaviour

## Related issues or tickets

https://docker.atlassian.net/browse/DKP-2524

## Reviews

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

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

Author: aevesdocker

content/manuals/admin/organization/setup/onboard.md

@@ -73,13 +73,13 @@ receive your Docker subscription benefits.
 
 1. Identify the Docker users in your organization.
    - If your organization uses device management software, like MDM or Jamf,
-     you can use the device management software to help identify Docker users.
-     See your device management software's documentation for details. You can
-     identify Docker users by checking if Docker Desktop is installed at the
-     following location on each user's machine:
-     - Mac: `/Applications/Docker.app`
-     - Windows: `C:\Program Files\Docker\Docker`
-     - Linux: `/opt/docker-desktop`
+   you can use the device management software to help identify Docker users.
+   See your device management software's documentation for details. You can
+   identify Docker users by checking if Docker Desktop is installed at the
+   following location on each user's machine:
+      - Mac: `/Applications/Docker.app`
+      - Windows: `C:\Program Files\Docker\Docker`(all-user installation) or `%LOCALAPPDATA%\Programs\DockerDesktop` (per-user installation (Beta))
+      - Linux: `/opt/docker-desktop`
    - If your organization doesn't use device management software or your
      users haven't installed Docker Desktop yet, you can survey your users to
      identify who is using Docker Desktop.

content/manuals/desktop/setup/install/windows-install.md

@@ -36,13 +36,29 @@ This page provides download links, system requirements, and step-by-step install
 
 _For checksums, see [Release notes](/manuals/desktop/release-notes.md)_
 
+## Installation modes
+ 
+Docker Desktop supports two installation modes. Per-user installation (Beta) is recommended for most users. It does not require administrator privileges to install or update, and the WSL 2 backend it uses covers the needs of the vast majority of Docker Desktop users.
+ 
+| | Per-user (recommended) | All users |
+|---|---|---|
+| Install location | `%LOCALAPPDATA%\Programs\DockerDesktop` | `C:\Program Files\Docker\Docker` |
+| Registry keys | Current User (HKCU) | Local Machine (HKLM) |
+| Admin rights to install | Not required | Required |
+| Admin rights to update | Not required | Required |
+| Linux containers backend | WSL 2 only | WSL 2 or Hyper-V |
+| Windows containers | Not supported | Supported |
+| Security | Smaller attack surface; no privileged system service installed | Requires privileged system service; broader access to host resources |
+
+For more information, see [Understand permission requirements for Windows](windows-install.md).
+
 ## System requirements
 
 > [!TIP]
 >
 > **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 setup 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. Note that Hyper-V is only available with all-users installation. If you install Docker Desktop in per-user mode, WSL 2 is the only supported backend. 
 
 {{< tabs >}}
 {{< tab name="WSL 2 backend, x86_64" >}}
@@ -131,7 +147,11 @@ For more information, see [Running Docker Desktop in a VM or VDI environment](/m
 
 1. Download the installer using the download button at the top of the page, or from the [release notes](/manuals/desktop/release-notes.md).
 
-2. Double-click `Docker Desktop Installer.exe` to run the installer. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`.
+2. Double-click `Docker Desktop Installer.exe` to run the installer. The installer will ask which installation mode you prefer. Choosing per-user installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and requires no administrator privileges. Choosing all users will prompt for elevation.
+
+   > [!NOTE]
+   >
+   >If you want to switch installation mode at a later date, you need to uninstall and reinstall Docker Desktop.
 
 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.
 
@@ -143,43 +163,54 @@ For more information, see [Running Docker Desktop in a VM or VDI environment](/m
 
 6. [Start Docker Desktop](#start-docker-desktop).
 
-If your administrator account is different to your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers:
+### Install from the command line
 
-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.
-4. Sign out and sign back in for the changes to take effect.
+After downloading `Docker Desktop Installer.exe`, run the following command in a terminal to install Docker Desktop to `%LOCALAPPDATA%\Programs\DockerDesktop`.
 
-### Install from the command line
+For per-user installation, run:
 
-After downloading `Docker Desktop Installer.exe`, run the following command in a terminal to install Docker Desktop:
+```console
+$ "Docker Desktop Installer.exe" install --user
+```
 
+To install for all users on the machine (requires administrator privileges):
+ 
 ```console
 $ "Docker Desktop Installer.exe" install
 ```
 
-If you’re using PowerShell you should run it as:
-
+If you're using PowerShell you should run it as:
+ 
 ```powershell
+# Per-user installation (no admin required)
+Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--user'
+ 
+# All-users installation (run as administrator)
 Start-Process 'Docker Desktop Installer.exe' -Wait install
 ```
 
 If using the Windows Command Prompt:
-
+ 
 ```sh
+# Per-user installation (no admin required)
+start /w "" "Docker Desktop Installer.exe" install --user
+ 
+# All-users installation (run as administrator)
 start /w "" "Docker Desktop Installer.exe" install
 ```
 
-By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`.
-
-If your administrator account is different to your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers.
+If using all-users installation and your administrator account is different to your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers:
 
 ```console
 $ net localgroup docker-users <user> /add
 ```
 
 See the [Installer flags](#installer-flags) section to see what flags the `install` command accepts.
 
+> [!NOTE]
+>
+>If you want to switch installation mode at a later date, you need to uninstall and reinstall Docker Desktop.
+
 ## Start Docker Desktop
 
 Docker Desktop does not start automatically after installation. To start Docker Desktop:
@@ -249,6 +280,8 @@ If Microsoft Store access is blocked due to security policies:
 
 #### Installation behavior
 
+
+- `--user`: Installs Docker Desktop in per-user mode, to `%LOCALAPPDATA%\Programs\DockerDesktop`. No administrator privileges are required. This is the recommended mode for most users. See [Installation modes](#installation-modes).
 - `--quiet`: Suppresses information output when running the installer 
 - `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run
 - `--installation-dir=<path>`: Changes the default installation location (`C:\Program Files\Docker\Docker`)
@@ -293,13 +326,19 @@ If Microsoft Store access is blocked due to security policies:
 
 ### Administrator privileges
 
-Installing Docker Desktop requires administrator privileges. However, once installed, it can be used without administrative access. Some actions, though, still need elevated permissions. See [Understand permission requirements for Windows](./windows-permission-requirements.md) for more detail.
+In per-user mode, Docker Desktop can be installed and updated without administrator privileges. Some settings still require elevation and are marked **Requires password** in the Settings UI. Enabling WSL 2 for the first time also requires administrator privileges, but this is a one-time, per-machine operation.
+
+In all-users mode, installing Docker Desktop requires administrator privileges. However, once installed, it can be used without administrative access. Some actions, though, still need elevated permissions. See [Understand permission requirements for Windows](./windows-permission-requirements.md) for more detail.
 
 See the [FAQs](/manuals/desktop/troubleshoot-and-support/faqs/general.md#how-do-i-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges.
 
 If you're an IT admin and your users do not have administrator rights and plan to perform operations that require elevated privileges, be sure to install Docker Desktop using the `--always-run-service` installer flag. This ensures those actions can still be executed without prompting for User Account Control (UAC) elevation. See [Installer Flags](#installer-flags) for more detail.
 
-### Windows containers 
+### Windows containers
+
+> [!NOTE]
+>
+> Windows containers are only supported in all-users installation mode. They are not available when Docker Desktop is installed per-user.
 
 From the Docker Desktop menu, you can toggle which daemon (Linux or Windows)
 the Docker CLI talks to. Select **Switch to Windows containers** to use Windows

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

@@ -12,28 +12,55 @@ 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.
 
-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.
+It also provides clarity on running containers as `root` as opposed to having `Administrator` access on the host and the privileges of 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. 
-
-Running Docker Desktop on Windows without the privileged helper does not require users to have `docker-users` group membership. However,
-some features that require privileged operations will have this requirement. 
-
-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 features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers.
-
+The permissions required to install and run Docker Desktop depend on which [installation mode](/manuals/desktop/setup/install/windows-install.md#installation-modes) you use.
+ 
+### Per-user installation (Beta)
+ 
+In per-user mode, Docker Desktop installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and writes only to current-user registry keys (`HKCU`). This means:
+ 
+- No administrator privileges are required to install or update Docker Desktop.
+- After installation, Docker Desktop can be run without administrator privileges.
+- Some settings marked **Requires password** in **Settings** still require elevation. When you change one of these settings and select **Apply**, Docker Desktop opens a UAC prompt for administrator access.
+ 
+Per-user installation does not install the privileged helper service `com.docker.service` automatically. As a result, features that depend on it, such as the Hyper-V backend and Windows containers, are not available. For most users this is not a limitation, as the WSL 2 backend covers the majority of use cases.
+ 
+### All-users installation
+ 
+In all-users mode, Docker Desktop installs to `C:\Program Files\Docker\Docker` and writes to Local Machine registry keys (`HKLM`). Both locations require administrator privileges to modify, so:
+ 
+- Administrator privileges are required to install and update Docker Desktop.
+- On installation you receive a UAC prompt which allows the privileged helper service `com.docker.service` to be installed.
+- After installation, Docker Desktop can be run without administrator privileges.
+ 
+Running Docker Desktop without the privileged helper does not require users to have `docker-users` group membership. However, some features that require privileged operations will have this requirement.
+ 
+If you performed the installation, you are automatically added to the `docker-users` group, but other users must be added manually. This allows the administrator to control who has access to features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers.
+ 
 When Docker Desktop launches, all non-privileged named pipes are created so that only the following users can access them:
 - The user that launched Docker Desktop.
 - Members of the local `Administrators` group.
 - The `LOCALSYSTEM` account.
+ 
+### Operations that always require elevation
+ 
+The following require administrator privileges regardless of installation mode.
+ 
+- Enabling WSL 2 for the first time: WSL 2 must be enabled on the machine before Docker Desktop can run. This is a one-time, per-machine operation. Once WSL 2 is enabled, it does not need to be enabled again for subsequent Docker Desktop installs or updates.
+- Settings marked **Requires password**: Certain Docker Desktop settings affect system-level configuration and require administrator credentials to apply. These are clearly marked **Requires password**. When you change one of these settings and select **Apply**, Docker Desktop prompts for administrator credentials.
 
 ## Privileged helper
 
 Docker Desktop needs to perform a limited set of privileged operations which are conducted by the privileged helper process `com.docker.service`. This approach allows, following the principle of least privilege, `Administrator` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.
 
+> [!NOTE]
+>
+> `com.docker.service` is only installed in all-users installation mode. It is not used in per-user installation, which instead relies solely on the WSL 2 backend and does not support Hyper-V or Windows containers.
 
 The privileged helper `com.docker.service` is a Windows service which runs in the background with `SYSTEM` privileges. It listens on the named pipe `//./pipe/dockerBackendV2`. The developer runs the Docker Desktop application, which connects to the named pipe and sends commands to the service. This named pipe is protected, and only users that are part of the `docker-users` group can have access to it.
 
@@ -84,6 +111,10 @@ isolated from the Docker daemon and other services running inside the VM.
 >
 > Enabling Windows containers has important security implications.
 
+> [!NOTE]
+>
+> Windows containers are only supported in all-users installation mode. They are not available when Docker Desktop is installed per-user. See [Installation modes](/manuals/desktop/setup/install/windows-install.md#installation-modes).
+
 Unlike the Linux Docker Engine and containers which run in a VM, Windows containers are implemented using operating system features, and run directly on the Windows host. If you enable Windows containers during installation, the `ContainerAdministrator` user used for administration inside the container is a local administrator on the host machine. Enabling Windows containers during installation makes it so that members of the `docker-users` group are able to elevate to administrators on the host. For organizations who don't want their developers to run Windows containers, a `-–no-windows-containers` installer flag is available to disable their use.
 
 ## Networking

content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md

@@ -94,13 +94,21 @@ Docker Desktop cannot start.
 1. Locate the `com.docker.diagnose` tool:
 
    ```console
+   # For all-user installations
    $ C:\Program Files\Docker\Docker\resources\com.docker.diagnose.exe
+
+   # For all-user installations
+   $ %LOCALAPPDATA%\Programs\DockerDesktop\resources\com.docker.diagnose.exe
    ```
 
 2. Create and upload the diagnostics ID. In PowerShell, run:
 
    ```console
+   # For all-user installations
    $ & "C:\Program Files\Docker\Docker\resources\com.docker.diagnose.exe" gather -upload
+
+   # For all-user installations
+   $ & %LOCALAPPDATA%\Programs\DockerDesktop\resources\com.docker.diagnose.exe" gather -upload
    ```
 
 After the diagnostics have finished, the terminal displays your diagnostics ID and the path to the diagnostics file. The diagnostics ID is composed of your user ID and a timestamp. For example `BE9AFAAF-F68B-41D0-9D12-84760E6B8740/20190905152051`.

content/manuals/desktop/uninstall.md

@@ -25,7 +25,11 @@ weight: 210
 
 1. Locate the installer:
    ```console
+   # all-user installation
    $ C:\Program Files\Docker\Docker\Docker Desktop Installer.exe
+
+   # per-user installation (Beta)
+   $ %LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe
    ```
 2. Uninstall Docker Desktop. 
  - In PowerShell, run:

content/manuals/desktop/use-desktop/kubernetes.md

@@ -28,7 +28,7 @@ With Docker Desktop version 4.51 and later, you can manage Kubernetes directly f
 4. Optional: Select **Show system containers (advanced)** to view internal containers when using Docker commands.
 5. Select **Create**. 
 
-This sets up the images required to run the Kubernetes server as containers, and installs the `kubectl` command-line tool on your system at `/usr/local/bin/kubectl` (Mac) or `C:\Program Files\Docker\Docker\resources\bin\kubectl.exe` (Windows). If you installed `kubectl` using Homebrew, or by some other method, and experience conflicts, remove `/usr/local/bin/kubectl`.
+This sets up the images required to run the Kubernetes server as containers, and installs the `kubectl` command-line tool on your system at `/usr/local/bin/kubectl` (Mac) or `C:\Program Files\Docker\Docker\resources\bin\kubectl.exe`(all-user installations) or `%LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\kubectl.exe` (per-user installations) (Windows). If you installed `kubectl` using Homebrew, or by some other method, and experience conflicts, remove `/usr/local/bin/kubectl`.
 
    > [!NOTE]
    >

content/manuals/enterprise/enterprise-deployment/faq.md

@@ -20,7 +20,12 @@ Common questions about installing Docker Desktop using the MSI installer.
 Users must [uninstall](/manuals/desktop/uninstall.md) older `.exe` installations before using the new MSI version. The `.exe` installer includes a `-keep-data` flag that removes Docker Desktop while preserving underlying resources such as the container VMs:
 
 ```powershell
+# For all-user installations
 & 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall -keep-data
+
+# For per-user installations
+& '%LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe' uninstall -keep-data
+
 ```
 
 ### What happens if the user's machine has an older `.exe` installation?