From ed686f1168f7c00ac1cc56ab6be546981f2bd03c Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 30 Sep 2026 10:55:58 +0100 Subject: [PATCH 1/2] freshness: DD deploy and enforce sign in Signed-off-by: aevesdocker --- .../enterprise/enforce-sign-in/_index.md | 48 +++++++--- .../enterprise/enforce-sign-in/methods.md | 87 ++++++++++++++++--- .../enterprise-deployment/_index.md | 2 +- .../enterprise-deployment/dev-box.md | 16 ++-- .../enterprise/enterprise-deployment/faq.md | 59 ++++++++++++- .../enterprise-deployment/ms-store.md | 6 +- .../msi-install-and-configure.md | 38 ++++---- .../pkg-install-and-configure.md | 18 ++-- .../unassociated-machines/_index.md | 64 ++++---------- data/summary.yaml | 1 + 10 files changed, 230 insertions(+), 109 deletions(-) diff --git a/content/manuals/desktop/enterprise/enforce-sign-in/_index.md b/content/manuals/desktop/enterprise/enforce-sign-in/_index.md index 6a958253128f..78027cde0769 100644 --- a/content/manuals/desktop/enterprise/enforce-sign-in/_index.md +++ b/content/manuals/desktop/enterprise/enforce-sign-in/_index.md @@ -19,10 +19,12 @@ When users don't sign in as organization members, they miss out on subscription You can enforce sign-in using several methods, depending on your setup: -- [Registry key method (Windows only)](methods.md#registry-key-method-windows-only) -- [Configuration profiles method (Mac only)](methods.md#configuration-profiles-method-mac-only) -- [`.plist` method (Mac only)](methods.md#plist-method-mac-only) -- [`registry.json` method (All)](methods.md#registryjson-method-all) +- [Registry key method (Windows only)](methods.md#windows-registry-key-method) +- [Configuration profiles method (Mac only)](methods.md#mac-configuration-profiles-method-recommended) +- [`.plist` method (Mac only)](methods.md#mac-plist-file-method) +- [`registry.json` method (all platforms)](methods.md#all-platforms-registryjson-method) + +Deploying a `admin-settings.json` file with [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) also enforces sign-in. See [Settings Management and sign-in enforcement](methods.md#settings-management-and-sign-in-enforcement). This page provides an overview of how sign-in enforcement works. @@ -31,23 +33,45 @@ This page provides an overview of how sign-in enforcement works. When Docker Desktop detects a registry key, configuration profile, `.plist` file, or `registry.json` file: -- A **Sign in required!** prompt appears, requiring users to sign - in as organization members to use Docker Desktop. +- A **Sign in using your work email address** prompt appears, requiring users to + sign in as organization members to use Docker Desktop. The prompt states which + organizations are required and which method enforced it. - If users sign in with accounts that aren't organization members, they're - automatically signed out and can't use Docker Desktop. They can select **Sign in** - to try again with a different account. + automatically signed out and can't use Docker Desktop. The prompt changes to + **You have been signed out** and explains why. They can sign in again with a + different account. - When users sign in with organization member accounts, they can use Docker Desktop normally. -- When users sign out, the **Sign in required!** prompt reappears and they can +- When users sign out, the sign-in prompt reappears and they can no longer use Docker Desktop unless they sign back in. -> [!NOTE] +### Impact on the Docker CLI + +Sign-in enforcement also blocks the Docker CLI. While the sign-in prompt is +showing, Docker Desktop's API proxy rejects almost every request with an +explanation at the terminal, for example: + +```text +Sign in to continue using Docker Desktop. Membership in the [myorg] organization +is required. Sign in enforced by your administrators (via registry.json). +``` + +- `docker run`, `docker pull`, `docker build`, `docker ps`, and other commands + that reach the engine fail until the user signs in. +- `docker version`, `docker info`, and `docker login` continue to work, so users + can sign in from the CLI. + +> [!IMPORTANT] > -> Enforcing sign-in for Docker Desktop doesn't affect Docker CLI access. CLI access is only restricted for organizations that enforce single sign-on (SSO). +> Plan for this before you roll out enforcement. Any scripted or CI use of the +> Docker CLI on an enforced machine stops working until that machine's user signs +> in as an organization member. + +Sign-in enforcement is separate from [SSO enforcement](#enforcing-sign-in-versus-enforcing-single-sign-on-sso), which governs how users authenticate rather than whether they must. ### Impact on already-signed-in users -When enforcement is first deployed, users who are already running Docker Desktop are not immediately affected. Docker Desktop only re-evaluates enforcement on restart. +When enforcement is first deployed, users who are already running Docker Desktop are not immediately affected. Docker Desktop re-evaluates enforcement when it starts, and when a user signs in or out. It doesn't poll for new configuration while running, so a newly deployed registry key, configuration profile, `.plist`, or `registry.json` file takes effect on the next restart. On the next Docker Desktop restart: diff --git a/content/manuals/desktop/enterprise/enforce-sign-in/methods.md b/content/manuals/desktop/enterprise/enforce-sign-in/methods.md index 6c97f2bac7d9..d6c8fc8eee36 100644 --- a/content/manuals/desktop/enterprise/enforce-sign-in/methods.md +++ b/content/manuals/desktop/enterprise/enforce-sign-in/methods.md @@ -47,6 +47,16 @@ To configure the registry key method manually: 1. Restart Docker Desktop. 1. Verify the **Sign in required!** prompt appears in Docker Desktop. +You can also create this key at install time with the MSI installer's +`ALLOWEDORG` property, which accepts multiple organizations separated by +semicolons: + +```powershell +msiexec /i "DockerDesktop.msi" /quiet /norestart ALLOWEDORG="myorg1;myorg2" +``` + +For more information, see [MSI installer](/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md#configuration-options). + {{< /tab >}} {{< tab name="Group Policy deployment" >}} @@ -84,8 +94,15 @@ The payload is a dictionary of key-values. Docker Desktop supports the following - `overrideProxyPAC`: Sets the file path where the PAC file is located. It has precedence over the remote PAC file on the selected proxy. - `overrideProxyEmbeddedPAC`: Sets the content of an in-memory PAC file. It has precedence over `overrideProxyPAC`. -Overriding at least one of the proxy settings via Configuration profiles will automatically lock the settings as they're managed by Mac. +> [!IMPORTANT] +> +> `allowedOrgs` must be a ``, not an ``. Docker Desktop only reads +> string values from a configuration profile, so an array is silently ignored and +> no enforcement happens. This differs from the +> [`.plist` method](#mac-plist-file-method), which does use an array. +Setting at least one of the proxy keys puts Docker Desktop's proxy into manual +mode and locks the proxy settings, so developers can't change them. 1. Create a file named `docker.mobileconfig` and include the following content: ```xml @@ -179,7 +196,7 @@ Some MDM solutions let you specify the payload as a plain dictionary of key-valu ``` 1. Set file permissions to prevent editing by non-administrator users. 1. Restart Docker Desktop. -1. Verify the `Sign in required!` prompt appears in Docker Desktop. +1. Verify the **Sign in using your work email address** prompt appears in Docker Desktop. {{< /tab >}} {{< tab name="Shell script deployment" >}} @@ -211,11 +228,11 @@ The registry.json method works across all platforms and offers flexible deployme ### File locations -Create the `registry.json` file (UTF-8 without BOM) at the appropriate location: +Create the `registry.json` file (UTF-8) at the appropriate location: | Platform | Location | | --- | --- | -| Windows | `/ProgramData/DockerDesktop/registry.json` | +| Windows | `%ProgramData%\DockerDesktop\registry.json` | | Mac | `/Library/Application Support/com.docker.docker/registry.json` | | Linux | `/usr/share/docker-desktop/registry/registry.json` | @@ -234,7 +251,7 @@ Create the `registry.json` file (UTF-8 without BOM) at the appropriate location: ``` 1. Set file permissions to prevent user editing. 1. Restart Docker Desktop. -1. Verify the `Sign in required!` prompt appears in Docker Desktop. +1. Verify the **Sign in using your work email address** prompt appears in Docker Desktop. > [!TIP] > @@ -271,6 +288,10 @@ Create the registry.json file during Docker Desktop installation: #### Windows +`--allowed-org` is a flag on the EXE installer. If you deploy with the MSI +installer, use the `ALLOWEDORG` property instead, which creates the +[registry key](#windows-registry-key-method). + ```shell # PowerShell Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg' @@ -283,6 +304,15 @@ Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myor > > The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. +> [!IMPORTANT] +> +> With Docker Desktop version 4.83 and later, `--allowed-org` can't be combined +> with `--user`, and it can't be used for a Microsoft Store installation. Both +> are per-user installations and the installer rejects the combination. This +> matters because the Windows installer selects a per-user installation by +> default from version 4.83. For per-user installations, configure the +> `registry.json` file after installation. + #### Mac ```console @@ -299,19 +329,52 @@ sudo hdiutil detach /Volumes/Docker ## Method precedence -When multiple configuration methods exist on the same system, Docker Desktop uses this precedence order: +When more than one configuration method exists on the same machine, Docker +Desktop evaluates them in order and stops at the first one that's configured. +The order depends on the platform. -1. Registry key (Windows only) -1. Configuration profiles (Mac only) -1. plist file (Mac only) -1. registry.json file +| Platform | Precedence order | +|:---------|:-----------------| +| Windows | 1. Registry key
2. `registry.json`
3. `admin-settings.json` | +| Mac | 1. Configuration profile
2. `desktop.plist`
3. `registry.json`
4. `admin-settings.json` | +| Linux | 1. `registry.json`
2. `admin-settings.json` | + +Lower-precedence methods are not consulted once a higher one applies. For +example, on a Mac with both a configuration profile and a `registry.json` file, +only the organizations in the configuration profile are enforced. + +## Settings Management and sign-in enforcement + +Deploying an `admin-settings.json` file enforces sign-in on its own, even if the +file contains no organization list. Users who aren't on a Docker Business +subscription see the sign-in prompt, and the Docker engine is held until they +sign in. + +This differs from the four methods above in two ways: + +- It doesn't restrict sign-in to particular organizations, so any Docker account + satisfies it. Combine it with one of the methods above if you need organization + membership enforced. +- It's the lowest-precedence method, so any of the methods above overrides it. + +If you use [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md), account for this when planning your rollout: developers who are signed out will be prompted to sign in as soon as the file reaches their machine and Docker Desktop restarts. ## Troubleshoot sign-in enforcement If sign-in enforcement doesn't work: - Verify file locations and permissions -- Check that organization names use lowercase letters -- Restart Docker Desktop or reboot the system +- Check that organization names use lowercase letters and match your Docker Hub + organization name exactly. Matching is case-sensitive, so a mismatch signs out + every user +- Check for stray whitespace in the value. In the Windows registry key, put each + organization on its own line rather than separating them with spaces or commas +- Check whether a higher-precedence method is in effect. See + [Method precedence](#method-precedence) +- Restart Docker Desktop or reboot the system. Docker Desktop doesn't pick up new + configuration while running - Confirm users are members of the specified organizations - Update Docker Desktop to the latest version + +If enforcement works but developers report that the Docker CLI stopped working, +that's expected. See [Impact on the Docker CLI](_index.md#impact-on-the-docker-cli). \ No newline at end of file diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/_index.md b/content/manuals/desktop/enterprise/enterprise-deployment/_index.md index e49f0024f8b5..a2d8bcc3e2ff 100644 --- a/content/manuals/desktop/enterprise/enterprise-deployment/_index.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/_index.md @@ -33,6 +33,6 @@ aliases: - /enterprise/enterprise-deployment/ --- -Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions like Intune or Jamf, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, macOS, and Linux systems. +Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions like Intune or Jamf, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, Mac, and Linux systems. {{< grid >}} \ No newline at end of file diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/dev-box.md b/content/manuals/desktop/enterprise/enterprise-deployment/dev-box.md index 1f2332ba0acd..d4db62ec1435 100644 --- a/content/manuals/desktop/enterprise/enterprise-deployment/dev-box.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/dev-box.md @@ -8,6 +8,12 @@ aliases: - /enterprise/enterprise-deployment/dev-box/ --- +> [!IMPORTANT] +> +> Microsoft has announced the retirement of Microsoft Dev Box. The service entered its closing-down period on 14 September 2026 and retires fully at 17:00 UTC on 18 September 2028. Microsoft recommends transitioning to Windows 365 or another solution. See the [Microsoft Dev Box retirement guide](https://learn.microsoft.com/en-us/azure/dev-box/dev-box-retirement-guide). +> +> To deploy Docker Desktop on Windows 365 Cloud PCs or other managed Windows machines, use the [MSI installer](msi-install-and-configure.md) with [Intune](use-intune.md). + Docker Desktop is available as a pre-configured image in the Microsoft Azure Marketplace for use with Microsoft Dev Box, allowing developers to quickly set up consistent development environments in the cloud. Microsoft Dev Box provides cloud-based, pre-configured developer workstations that allow you to code, build, and test applications without configuring a local development environment. The Docker Desktop image for Microsoft Dev Box comes with Docker Desktop and its dependencies pre-installed, giving you a ready-to-use containerized development environment. @@ -34,17 +40,17 @@ Microsoft Dev Box provides cloud-based, pre-configured developer workstations th ### Set up Docker Desktop in Dev Box 1. Navigate to the [Docker Desktop for Microsoft Dev Box](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/dockerinc1694120899427.devbox_azuremachine?tab=Overview) listing in Azure Marketplace. -2. Select **Get It Now** to add the virtual machine image to your subscription. -3. Follow the Azure workflow to complete the setup. -4. Use the image to create VMs, assign to Dev Centers, or create Dev Box Pools according to your organization's setup. +1. Select **Get It Now** to add the virtual machine image to your subscription. +1. Follow the Azure workflow to complete the setup. +1. Use the image to create VMs, assign to Dev Centers, or create Dev Box Pools according to your organization's setup. ### Activate Docker Desktop Once your Dev Box is provisioned with the Docker Desktop image: 1. Start your Dev Box instance. -2. Launch Docker Desktop. -3. Sign in with your Docker ID. +1. Launch Docker Desktop. +1. Sign in with your Docker ID. ## Support diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/faq.md b/content/manuals/desktop/enterprise/enterprise-deployment/faq.md index 84ac3eed6b27..e1107dd6bd69 100644 --- a/content/manuals/desktop/enterprise/enterprise-deployment/faq.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/faq.md @@ -15,20 +15,71 @@ 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`)? -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: +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 +& '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 +& '%LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe' uninstall --keep-data ``` +For all-users installations, you can have the MSI do this for you with the `REMOVEEXISTINGINSTALL` property, described in the next answer. + +### What happens if the user's machine has an older `.exe` installation? + ### What happens if the user's machine has an older `.exe` installation? -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. +The MSI installer detects existing `.exe` installations and, by default, blocks the installation. How you resolve it depends on whether the `.exe` was installed for all users or for a single user. + +#### All-users `.exe` installation + +The installation stops with: + +```text +You need to uninstall the previous Docker Desktop version in order to use the MSI installer. +``` + +Either uninstall it first with `--keep-data` as described in the previous answer, or let the MSI do it by setting `REMOVEEXISTINGINSTALL=1`: + +```powershell +msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart REMOVEEXISTINGINSTALL=1 +``` + +This runs the existing uninstaller with `--keep-data`, so settings and container data are preserved. `REMOVEEXISTINGINSTALL` defaults to `0` and is available with Docker Desktop version 4.30 and later. + +#### Per-user `.exe` installation + +Available with Docker Desktop version 4.84 and later, the installation stops with: + +```text +Docker Desktop is installed per-user for one or more accounts on this machine: . +Please have each affected user uninstall Docker Desktop first before running the MSI installer. +``` + +`REMOVEEXISTINGINSTALL` doesn't help here. The MSI runs with machine-wide privileges and can't reliably uninstall software installed under another user's profile, so each listed user must uninstall Docker Desktop themselves before the MSI can proceed. + +With Docker Desktop version 4.83 and earlier, the MSI doesn't detect per-user installations. + +> [!NOTE] +> +> Per-user installations became more common with Docker Desktop version 4.83, when the EXE installer started selecting a per-user installation by default. Expect to encounter them on machines where developers installed Docker Desktop themselves. + +### Can I install the MSI per-user? + +No. The MSI installer only supports all-users installations. + +Available with Docker Desktop version 4.92 and later, passing `MSIINSTALLPERUSER` fails with: + +```text +Docker Desktop does not support per-user installation with the MSI installer. +``` + +With Docker Desktop version 4.91 and earlier, the MSI accepts `MSIINSTALLPERUSER` but produces an installation that later updates can't upgrade. + +Use the EXE installer with the `--user` flag if you need a per-user installation. ### My installation failed, how do I find out what happened? diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/ms-store.md b/content/manuals/desktop/enterprise/enterprise-deployment/ms-store.md index 6b21e14e6d86..7501a3bf9230 100644 --- a/content/manuals/desktop/enterprise/enterprise-deployment/ms-store.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/ms-store.md @@ -28,7 +28,7 @@ For developers who install Docker Desktop directly: ### Intune-managed installations In environments managed with Intune: -- Intune checks for updates approximately every 8 hours. +- - Intune checks for updates periodically, typically several times a day. The exact interval is controlled by Intune, not by Docker. - When a new version is detected, Intune triggers a `winget` upgrade. - If appropriate policies are configured, updates can occur automatically without user intervention. - Updates are handled by Intune's management infrastructure rather than the Microsoft Store itself. @@ -45,3 +45,7 @@ If using Intune to manage Docker Desktop for Windows: - Ensure your Intune policies are configured to handle application updates - Be aware that the update process uses WinGet APIs rather than direct Store mechanisms - Consider testing the update process in a controlled environment to verify proper functionality + +## Installation mode + +Available with Docker Desktop version 4.85 and later, fresh installations from the Microsoft Store use per-user install mode by default, which removes the need for admin privileges. diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md b/content/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md index 8f0490dc1f74..1cab5fdc5f47 100644 --- a/content/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/msi-install-and-configure.md @@ -16,33 +16,31 @@ The MSI package supports various MDM (Mobile Device Management) solutions, makin ## Install interactively 1. In [Docker Home](http://app.docker.com), choose your organization. -2. Select **Docker Desktop**, then **Deploy**. -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. After accepting the license agreement, choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`(all-user installations) or `%LOCALAPPDATA%\Programs\DockerDesktop` (per-user installations) -6. Configure the Docker Desktop installation. You can: +1. Select **Docker Desktop**, then **Deploy**. +1. From the **Windows OS** tab, select the **Download MSI installer** button. +1. Once downloaded, double-click `DockerDesktop.msi` to run the installer. +1. After accepting the license agreement, choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`. The MSI installer only supports all-users installations (version 4.92 and later). If you need a per-user installation, use the EXE installer. +1. Configure the Docker Desktop installation. You can: - Create a desktop shortcut - Set the Docker Desktop service startup type to automatic - - Disable Windows Container usage + - Allow Windows Containers to be used with this installation. With Docker Desktop version 4.40 and later, this is cleared by default in the installation wizard, so Windows containers are disabled unless you select it. - - 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. + - Select the Docker Desktop backend: WSL or Hyper-V. +1. Follow the instructions on the installation wizard to authorize the installer and proceed with the install. +1. When the installation is successful, select **Finish** to complete the installation process. If your administrator account is different from 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: 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. +1. Navigate to **Local Users and Groups** > **Groups** > **docker-users**. +1. Right-click to add the user to the group. +1. Sign out and sign back in for the changes to take effect. > [!NOTE] > -> When installing Docker Desktop with the MSI, in-app updates are automatically disabled by default. This ensures organizations can maintain version consistency and prevent unapproved updates. -> Starting with Docker Desktop version 4.60 and later, in-app updates from an MSI installation can be enabled by changing the `disableUpdate` setting to `false` through [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). +> When installing Docker Desktop with the MSI, in-app updates are automatically disabled by default. This ensures organizations can maintain version consistency and prevent unapproved updates. In-app updates from an MSI installation can be enabled by changing the `disableUpdate` setting to `false` through [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md). > > Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from Docker Home. Navigate to the **Deploy** page. > @@ -100,7 +98,7 @@ msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart ADMINSETTINGS="{""configurationFileVersion"":2,""enhancedContainerIsolation"":{""value"":true,""locked"":false}}" ALLOWEDORG="your-organization" ``` -#### Install interactively and allow users to switch to Windows containers without admin rights +#### Install non-interactively and allow users to switch to Windows containers without admin rights ```powershell msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart ALLOWEDORG="your-organization" ALWAYSRUNSERVICE=1 @@ -201,11 +199,11 @@ In addition to the following custom properties, the Docker Desktop MSI installer | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | | `ENABLEDESKTOPSHORTCUT` | Creates a desktop shortcut. | 1 | | `INSTALLFOLDER` | Specifies a custom location where Docker Desktop will be installed. | C:\Program Files\Docker | -| `ADMINSETTINGS` | Automatically creates an `admin-settings.json` file which is used to [control certain Docker Desktop settings](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) on client machines within organizations. It must be used together with the `ALLOWEDORG` property. | None | +| `ADMINSETTINGS` | Automatically creates an `admin-settings.json` file which is used to [control certain Docker Desktop settings](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) on client machines within organizations. It must be used together with the `ALLOWEDORG` property. If you pass `ADMINSETTINGS` on its own, the installation still succeeds but no `admin-settings.json` file is written and no error is reported. | None | | `ALLOWEDORG` | Requires the user to sign in and be part of the specified Docker Hub organization when running the application. This creates a registry key called `allowedOrgs` in `HKLM\Software\Policies\Docker\Docker Desktop`. | None | | `ALWAYSRUNSERVICE` | Lets users switch to Windows containers without needing admin rights | 0 | | `DISABLEWINDOWSCONTAINERS` | Disables the Windows containers integration | 0 | -| `ENGINE` | Sets the Docker Engine that's used to run containers. This can be either `wsl` , `hyperv`, or `windows` | `wsl` | +| `ENGINE` | Sets the Docker Engine that's used to run containers. This can be `wsl`, `hyperv`, `windows`, or `docker-vmm`. The installation wizard only offers `wsl` and `hyperv`. The others are command line only. `docker-vmm` is available with Docker Desktop version 4.90 and later. | `wsl` | | `PROXYENABLEKERBEROSNTLM` | When set to 1, enables support for Kerberos and NTLM proxy authentication. | 0 | | `PROXYHTTPMODE` | Sets the HTTP Proxy mode. This can be either `system` or `manual` | `system` | | `OVERRIDEPROXYHTTP` | Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests. | None | @@ -217,7 +215,7 @@ In addition to the following custom properties, the Docker Desktop MSI installer | `WINDOWSCONTAINERSDEFAULTDATAROOT` | Specifies the default location for Windows containers. | None | | `WSLDEFAULTDATAROOT` | Specifies the default location for the WSL distribution disk. | None | | `DISABLEANALYTICS` | When set to 1, analytics collection will be disabled for the MSI. For more information, see [Analytics](#analytics). | 0 | -| `REMOVEEXISTINGINSTALL` | When set to 1, any existing EXE installations are removed. Existing settings and content are preserved. Available with Docker Desktop version 4.61 and later. | 1 | +| `REMOVEEXISTINGINSTALL` | When set to 1, an existing all-users EXE installation is uninstalled before the MSI installs, and settings and content are preserved. Has no effect on per-user EXE installations, which must be removed by the users who own them. | 1 | Additionally, you can also use `/norestart` or `/forcerestart` to control reboot behaviour. @@ -240,7 +238,7 @@ When you install Docker Desktop from the default installer GUI, select the **Dis When you install Docker Desktop from the command line, use the `DISABLEANALYTICS` property. ```powershell -msiexec /i "win\msi\bin\en-US\DockerDesktop.msi" /L*V ".\msi.log" DISABLEANALYTICS=1 +msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" DISABLEANALYTICS=1 ``` {{< /tab >}} diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md b/content/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md index 832cbaa02ad0..fbb11b3f75eb 100644 --- a/content/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/pkg-install-and-configure.md @@ -1,6 +1,6 @@ --- title: PKG installer -description: Understand how to use the PKG installer. Also explore additional configuration options. +description: Understand how to use the PKG installer to deploy Docker Desktop for Mac at scale. keywords: pkg, mac, docker desktop, install, deploy, configure, admin, mdm tags: [admin] weight: 20 @@ -15,10 +15,10 @@ The PKG package supports various MDM (Mobile Device Management) solutions, makin ## Install interactively 1. In [Docker Home](http://app.docker.com), choose your organization. -2. Select **Docker Desktop**, then **Deploy**. -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 installation. +1. Select **Docker Desktop**, then **Deploy**. +1. From the **macOS** tab, select the **Download PKG installer** button. +1. Once downloaded, double-click `Docker.pkg` to run the installer. +1. 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**. @@ -37,9 +37,9 @@ The PKG package supports various MDM (Mobile Device Management) solutions, makin ## Install from the command line 1. In [Docker Home](http://app.docker.com), choose your organization. -2. Select **Docker Desktop**, then **Deploy**. -3. From the **macOS** tab, select the **Download PKG installer** button. -4. From your terminal, run the following command: +1. Select **Docker Desktop**, then **Deploy**. +1. From the **macOS** tab, select the **Download PKG installer** button. +1. From your terminal, run the following command: ```console $ sudo installer -pkg "/path/to/Docker.pkg" -target /Applications @@ -48,4 +48,4 @@ The PKG package supports various MDM (Mobile Device Management) solutions, makin ## Additional resources - 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/desktop/enterprise/enforce-sign-in/methods.md#plist-method-mac-only) for your users. \ No newline at end of file +- Explore how to [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/methods.md#mac-plist-file-method) for your users. \ No newline at end of file diff --git a/content/manuals/desktop/enterprise/unassociated-machines/_index.md b/content/manuals/desktop/enterprise/unassociated-machines/_index.md index 2783de75d91b..c0c6861d64f0 100644 --- a/content/manuals/desktop/enterprise/unassociated-machines/_index.md +++ b/content/manuals/desktop/enterprise/unassociated-machines/_index.md @@ -9,24 +9,12 @@ aliases: {{< summary-bar feature_name="Unassociated machines" >}} -Docker administrators can identify, view, and manage Docker Desktop machines -that are likely associated with their organization but aren't currently linked +Organization owners can identify, view, and manage Docker Desktop machines +that are likely associated with their organization, based on usage, but aren't currently linked to user accounts. This self-service capability helps you understand Docker Desktop usage across your organization and streamline user onboarding without IT involvement. -## Prerequisites - -- Docker Business or Team subscription -- Organization owner access to your Docker organization - -## About unassociated machines - -Unassociated machines are Docker Desktop instances that Docker has identified -as likely belonging to your organization based on usage patterns, but the users -are not signed in to Docker Desktop with an account that is part of your -organization. - ## How Docker identifies unassociated machines Docker uses telemetry data to identify which machines likely belong to your @@ -63,7 +51,7 @@ You can: ## Enable sign-in enforcement for unassociated machines -> [!NOTE] +> [!IMPORTANT] > > Sign-in enforcement for unassociated machines is different from > the [organization-level sign-in enforcement](/manuals/desktop/enterprise/enforce-sign-in/_index.md) @@ -84,12 +72,7 @@ You can enable sign-in enforcement using two methods: - For all unassociated machines in your organization - For individual unassociated machines -> [!IMPORTANT] -> -> Sign-in enforcement only takes effect after Docker Desktop is restarted. -> Users can continue using Docker Desktop until their next restart. - -### Enable sign-in enforcement for all unassociated machines +### Enable for all unassociated machines To enable sign-in enforcement for all unassociated machines: @@ -98,19 +81,19 @@ To enable sign-in enforcement for all unassociated machines: 1. Turn on the **Enforce sign-in** toggle. 1. In the pop-up modal, select **Require sign-in** to confirm. -The **Sign-in required** status will update for all unassociated machines to +The **Sign-in required** status updates all unassociated machines to **Yes**. +Sign-in enforcement only takes effect after Docker Desktop is restarted. +Users can continue using Docker Desktop until their next restart. + > [!NOTE] > > When you enable sign-in enforcement for all unassociated machines, any new -> machines detected in the future will automatically have sign-in enforcement -> enabled. Sign-in enforcement requires Docker Desktop version 4.41 or later. -> Users with older versions will not be prompted to sign in and can continue -> using Docker Desktop normally until they update. Their status shows -> as **Pending** until they update to version 4.41 or later. +> machines detected in the future automatically have sign-in enforcement +> enabled. -### Enable sign-in enforcement for individual unassociated machines +### Enable for individual unassociated machines To enable sign-in enforcement for individual unassociated machines: @@ -120,26 +103,17 @@ To enable sign-in enforcement for individual unassociated machines: 1. Select the **Actions** menu and choose **Turn on sign-in enforcement**. 1. In the pop-up modal, select **Require sign-in** to confirm. -The **Sign-in required** status will update for the individual machine to +The **Sign-in required** status updates for the individual machine to **Yes**. -> [!NOTE] -> -> Sign-in enforcement requires Docker Desktop version 4.41 or later. Users -> with older versions will not be prompted to sign in and can continue using -> Docker Desktop normally until they update. Their status shows as **Pending** -> until they update to version 4.41 or later. - -### What happens when users sign in +### What happens sign-in is enforced After you enable sign-in enforcement: -1. Users must restart Docker Desktop. Enforcement only takes effect after - restart. -1. When users open Docker Desktop, they see a sign-in prompt. They must sign +- When users open Docker Desktop, they see a sign-in prompt. They must sign in to continue using Docker Desktop. -1. User email addresses appear in the **Unassociated** list. -1. You can add users to your organization. +- User email addresses appear in the **Unassociated** list. +- You can add users to your organization. Users can continue using Docker Desktop immediately after signing in, even before being added to your organization. @@ -166,7 +140,7 @@ organization in two ways: > [!NOTE] > > If you add users and do not have enough seats in your organization, a -> pop-up will appear prompting you to **Get more seats**. +> pop-up appears prompting you to **Get more seats**. ### Add individual users @@ -194,7 +168,7 @@ organization in two ways: 1. Turn off the **Enforce sign-in** toggle. 1. In the pop-up modal, select **Turn off sign-in requirement** to confirm. -The **Sign-in required** status will update for all unassociated machines to +The **Sign-in required** status updates for all unassociated machines to **No**. ### Disable for specific unassociated machines @@ -205,5 +179,5 @@ The **Sign-in required** status will update for all unassociated machines to 1. Select the **Actions** menu and choose **Turn off sign-in enforcement**. 1. In the pop-up modal, select **Turn off sign-in requirement** to confirm. -The **Sign-in required** status will update for the individual machine to +The **Sign-in required** status updates for the individual machine to **No**. diff --git a/data/summary.yaml b/data/summary.yaml index 5af3b18695d8..64bf2a180564 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -290,6 +290,7 @@ Synchronized file sharing: subscription: [Pro, Team, Business] Unassociated machines: for: Administrators + subscription: [Team, Business] USB/IP support: for: Docker Desktop for Mac, Linux, and Windows with the Hyper-V backend VMM: From c4cd5de22d2ff0dbd46704cae36f759c531ecc13 Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Wed, 30 Sep 2026 15:43:35 +0100 Subject: [PATCH 2/2] review edits Signed-off-by: aevesdocker --- .../enterprise/enforce-sign-in/_index.md | 6 +++--- .../enterprise/enforce-sign-in/methods.md | 18 ++++++------------ .../enterprise/enterprise-deployment/_index.md | 4 +++- 3 files changed, 12 insertions(+), 16 deletions(-) diff --git a/content/manuals/desktop/enterprise/enforce-sign-in/_index.md b/content/manuals/desktop/enterprise/enforce-sign-in/_index.md index 78027cde0769..615d23b8719c 100644 --- a/content/manuals/desktop/enterprise/enforce-sign-in/_index.md +++ b/content/manuals/desktop/enterprise/enforce-sign-in/_index.md @@ -35,7 +35,7 @@ When Docker Desktop detects a registry key, configuration profile, `.plist` file - A **Sign in using your work email address** prompt appears, requiring users to sign in as organization members to use Docker Desktop. The prompt states which - organizations are required and which method enforced it. + organizations are required and which method enforces it. - If users sign in with accounts that aren't organization members, they're automatically signed out and can't use Docker Desktop. The prompt changes to **You have been signed out** and explains why. They can sign in again with a @@ -63,11 +63,11 @@ is required. Sign in enforced by your administrators (via registry.json). > [!IMPORTANT] > -> Plan for this before you roll out enforcement. Any scripted or CI use of the +> Make sure you plan for blocking the Docker CLI before you roll out enforcement. Any scripted or CI use of the > Docker CLI on an enforced machine stops working until that machine's user signs > in as an organization member. -Sign-in enforcement is separate from [SSO enforcement](#enforcing-sign-in-versus-enforcing-single-sign-on-sso), which governs how users authenticate rather than whether they must. +Sign-in enforcement is separate from [SSO enforcement](#enforcing-sign-in-versus-enforcing-single-sign-on-sso), which governs how users authenticate as opposed to whether they must authenticate. ### Impact on already-signed-in users diff --git a/content/manuals/desktop/enterprise/enforce-sign-in/methods.md b/content/manuals/desktop/enterprise/enforce-sign-in/methods.md index d6c8fc8eee36..165ba3a0e38a 100644 --- a/content/manuals/desktop/enterprise/enforce-sign-in/methods.md +++ b/content/manuals/desktop/enterprise/enforce-sign-in/methods.md @@ -253,10 +253,8 @@ Create the `registry.json` file (UTF-8) at the appropriate location: 1. Restart Docker Desktop. 1. Verify the **Sign in using your work email address** prompt appears in Docker Desktop. -> [!TIP] -> -> If users have issues starting Docker Desktop after enforcing sign-in, -> they may need to update to the latest version. +If users have issues starting Docker Desktop after enforcing sign-in, +they may need to update to the latest version. {{< /tab >}} {{< tab name="Command line setup" >}} @@ -299,10 +297,7 @@ Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myor # Command Prompt "Docker Desktop Installer.exe" install --allowed-org=myorg1 ``` - -> [!NOTE] -> -> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. +The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. > [!IMPORTANT] > @@ -320,9 +315,8 @@ sudo hdiutil attach Docker.dmg sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg sudo hdiutil detach /Volumes/Docker ``` -> [!NOTE] -> -> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. + +The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation. {{< /tab >}} {{< /tabs >}} @@ -347,7 +341,7 @@ only the organizations in the configuration profile are enforced. Deploying an `admin-settings.json` file enforces sign-in on its own, even if the file contains no organization list. Users who aren't on a Docker Business -subscription see the sign-in prompt, and the Docker engine is held until they +subscription see the sign-in prompt, and the Docker Engine is held until they sign in. This differs from the four methods above in two ways: diff --git a/content/manuals/desktop/enterprise/enterprise-deployment/_index.md b/content/manuals/desktop/enterprise/enterprise-deployment/_index.md index a2d8bcc3e2ff..7479bc70ce54 100644 --- a/content/manuals/desktop/enterprise/enterprise-deployment/_index.md +++ b/content/manuals/desktop/enterprise/enterprise-deployment/_index.md @@ -33,6 +33,8 @@ aliases: - /enterprise/enterprise-deployment/ --- -Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions like Intune or Jamf, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, Mac, and Linux systems. +Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. + +Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, Mac, and Linux systems. {{< grid >}} \ No newline at end of file