mirror of https://github.com/docker/docs.git
ENGDOCS-2060 (#19793)
* ENGDOCS-2060 * ENGDOCS-2060 * fix build * language tweaks * first round refinements * fix build * review feedback and additions * review feedback and additions * review feedback and additions * Update opening paragraph * add intune * add intune * captain's feedback * further additions * further additions * add analytics.md * latest docs changes and additions * latest docs changes and additions * fix toc * fix toc * final tweaks * review tweak * review edits"
This commit is contained in:
Allie Sadler
GitHub
parent
e6847231e2
commit
91ab0808f6
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
title: Deploy with Microsoft installer
|
||||
description: If you're an IT admin, learn how to deploy Docker Desktop with Microsoft installer
|
||||
keywords: msi, docker desktop, windows, installation
|
||||
---
|
||||
|
||||
> **Early Access**
|
||||
>
|
||||
> The MSI installer is an [early access](../../../release-lifecycle.md#early-access-ea) feature.
|
||||
> It's available to all company owners and organization owners with Docker Desktop version 4.32 and later.
|
||||
{ .restricted }
|
||||
|
||||
Docker offers a 64-bit Microsoft Installer (MSI) package designed to assist IT administrators in customizing and deploying Docker Desktop across multiple users or machines in an enterprise environment.
|
||||
|
||||
The MSI package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations.
|
||||
|
||||
Whether you're looking to implement scripted installations or integrate Docker Desktop with existing MDM solutions, this MSI package is an essential resource.
|
||||
|
||||
## What's next
|
||||
|
||||
- [Use the Microsoft installer and read the configuration options](install-and-configure.md)
|
||||
- [Read the FAQs](faq.md)
|
||||
- [Install with Intune](use-intune.md)
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: MSI FAQs
|
||||
description: Frequently asked questions for deploying Docker Desktop with Microsoft installer
|
||||
keywords: msi, deploy, docker desktop, faqs
|
||||
tags: [FAQ]
|
||||
---
|
||||
|
||||
### 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](../../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](../../backup-and-restore.md) any containers that they want to keep.
|
||||
|
||||
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.
|
||||
|
||||
```powershell
|
||||
& 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall -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.
|
||||
|
||||
### 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.
|
||||
|
||||
To debug a failed installation, run the install again with verbose logging enabled:
|
||||
|
||||
```powershell
|
||||
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log"
|
||||
```
|
||||
|
||||
After the installation has failed, open the log file and search for occurrences of `value 3`. This is the exit code Windows Installer outputs when it has failed. Just above the line, you will find the reason for the failure.
|
||||
|
||||
### Why does the installer prompt for a reboot at the end of every fresh installation?
|
||||
|
||||
The installer prompts for a reboot because it assumes that changes have been made to the system that require a reboot to finish their configuration.
|
||||
|
||||
For example, if you select the WSL engine, the installer adds the required Windows features. After these features are installed, the system reboots to complete configurations so the WSL engine is functional.
|
||||
|
||||
You can suppress reboots by using the `/norestart` option when launching the installer from the command line:
|
||||
|
||||
```powershell
|
||||
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /norestart
|
||||
```
|
||||
|
|
@ -0,0 +1,244 @@
|
|||
---
|
||||
title: Install and configure
|
||||
description: Understand how to use the MSI installer. Also explore additional configuration options.
|
||||
keywords: msi, windows, docker desktop, install, deploy, configure
|
||||
---
|
||||
|
||||
## Install interactively
|
||||
|
||||
1. In the [Docker Admin Console](http://admin.docker.com/), navigate to your organization.
|
||||
|
||||
2. Under **Security and access**, select the **Deploy Docker Desktop** page.
|
||||
|
||||
3. 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`.
|
||||
|
||||
6. Configure the Docker Desktop installation. You can:
|
||||
|
||||
- Create a desktop shortcut
|
||||
|
||||
- Set the Docker Desktop service startup type to automatic
|
||||
|
||||
- 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.
|
||||
|
||||
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:
|
||||
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.
|
||||
|
||||
## Install from the command line
|
||||
|
||||
This section covers command line installations of Docker Desktop using PowerShell. It provides common installation commands that you can run. You can also add additional arguments which are outlined in [configuration options](#configuration-options).
|
||||
|
||||
When installing Docker Desktop, you can choose between interactive or non-interactive installations.
|
||||
|
||||
Interactive installations, without specifying `/quiet` or `/qn`, display the user interface and let you select your own properties.
|
||||
|
||||
When installing via the user interface it's possible to:
|
||||
|
||||
- Choose the destination folder
|
||||
- Create a desktop shortcut
|
||||
- Configure the Docker Desktop service startup type
|
||||
- Disable Windows Containers
|
||||
- Choose between the WSL or Hyper-V engine
|
||||
|
||||
Non-interactive installations are silent and any additional configuration must be passed as arguments.
|
||||
|
||||
### Common installation commands
|
||||
|
||||
> **Important**
|
||||
>
|
||||
> Admin rights are required to run any of the following commands.
|
||||
{ .important }
|
||||
|
||||
#### Installing interactively with verbose logging
|
||||
|
||||
```powershell
|
||||
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log"
|
||||
```
|
||||
|
||||
#### Installing interactively without verbose logging
|
||||
|
||||
```powershell
|
||||
msiexec /i "DockerDesktop.msi"
|
||||
```
|
||||
|
||||
#### Installing non-interactively with verbose logging
|
||||
|
||||
```powershell
|
||||
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet
|
||||
```
|
||||
|
||||
#### Installing non-interactively and suppressing reboots
|
||||
|
||||
```powershell
|
||||
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart
|
||||
```
|
||||
|
||||
#### Installing non-interactively with admin settings
|
||||
|
||||
```powershell
|
||||
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart ADMINSETTINGS="{"configurationFileVersion":2,"enhancedContainerIsolation":{"value":true,"locked":false}}" ALLOWEDORG="docker.com"
|
||||
```
|
||||
|
||||
#### Installing with the passive display option
|
||||
|
||||
You can use the `/passive` display option instead of `/quiet` when you want to perform a non-interactive installation but show a progress dialog.
|
||||
|
||||
In passive mode the installer doesn't display any prompts or error messages to the user and the installation cannot be cancelled.
|
||||
|
||||
For example:
|
||||
|
||||
```powershell
|
||||
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:
|
||||
>
|
||||
> - The property expects a JSON formatted string
|
||||
> - The string should be wrapped in double quotes
|
||||
> - The string shouldn't contain any whitespace
|
||||
> - Property names are expected to be in double quotes
|
||||
{ .tip }
|
||||
|
||||
### Common uninstall commands
|
||||
|
||||
When uninstalling Docker Desktop, you need to use the same `.msi` file that was originally used to install the application.
|
||||
|
||||
If you no longer have the original `.msi` file, you need to use the product code associated with the installation. To find the product code, run:
|
||||
|
||||
```powershell
|
||||
Get-WmiObject Win32_Product | Select-Object IdentifyingNumber, Name | Where-Object {$_.Name -eq "Docker Desktop"}
|
||||
```
|
||||
|
||||
It should return output similar to the following:
|
||||
|
||||
```text
|
||||
IdentifyingNumber Name
|
||||
----------------- ----
|
||||
{10FC87E2-9145-4D7D-B493-2E99E8D8E103} Docker Desktop
|
||||
```
|
||||
> **Note**
|
||||
>
|
||||
> This command can take some time to return, depending on the number of installed applications.
|
||||
|
||||
`IdentifyingNumber` is the applications product code and can be used to uninstall Docker Desktop. For example:
|
||||
|
||||
```powershell
|
||||
msiexec /x {10FC87E2-9145-4D7D-B493-2E99E8D8E103} /L*V ".\msi.log" /quiet
|
||||
```
|
||||
|
||||
#### Uninstalling interactively with verbose logging
|
||||
|
||||
```powershell
|
||||
msiexec /x "DockerDesktop.msi" /L*V ".\msi.log"
|
||||
```
|
||||
|
||||
#### Uninstalling interactively without verbose logging
|
||||
|
||||
```powershell
|
||||
msiexec /x "DockerDesktop.msi"
|
||||
```
|
||||
|
||||
#### Uninstalling non-interactively with verbose logging
|
||||
|
||||
```powershell
|
||||
msiexec /x "DockerDesktop.msi" /L*V ".\msi.log" /quiet
|
||||
```
|
||||
|
||||
#### Uninstalling non-interactively without verbose logging
|
||||
|
||||
```powershell
|
||||
msiexec /x "DockerDesktop.msi" /quiet
|
||||
```
|
||||
|
||||
### Configuration options
|
||||
|
||||
> **Important**
|
||||
>
|
||||
> In addition to the following custom properties, the Docker Desktop MSI installer also supports the standard [Windows Installer command line options](https://learn.microsoft.com/en-us/windows/win32/msi/standard-installer-command-line-options).
|
||||
{ .important }
|
||||
|
||||
| Property | Description | Default |
|
||||
| :--- | :--- | :--- |
|
||||
| `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](../../hardened-desktop/settings-management/_index.md) on client machines within organizations. It must be used together with the `ALLOWEDORG` property. | 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` |
|
||||
| `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 |
|
||||
| `OVERRIDEPROXYHTTPS` | Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests. | None |
|
||||
| `OVERRIDEPROXYEXCLUDE` | Bypasses proxy settings for the hosts and domains. Uses a comma-separated list. | None |
|
||||
| `HYPERVDEFAULTDATAROOT` | Specifies the default location for the Hyper-V VM disk. | None |
|
||||
| `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 |
|
||||
|
||||
|
||||
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.
|
||||
|
||||
## Updates
|
||||
|
||||
When installing Docker Desktop with the MSI, in-app updates are disabled.
|
||||
|
||||
Docker Desktop will notify you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Deploy Docker Desktop** page under **Security and access**.
|
||||
|
||||
To keep up to date with new releases, you can check use the [release notes](https://docs.docker.com/desktop/release-notes/) page.
|
||||
|
||||
## Analytics
|
||||
|
||||
The MSI installer collects data to better understand user behaviour and to improve the user experience by identifying and addressing issues or optimizing popular features.
|
||||
|
||||
### How to opt-out
|
||||
|
||||
{{< tabs >}}
|
||||
{{< tab name="From the GUI" >}}
|
||||
|
||||
When you install Docker Desktop from the default installer GUI, select the **Disable analytics** checkbox located on the bottom-left corner of the **Welcome** dialog.
|
||||
|
||||
{{< /tab >}}
|
||||
{{< tab name="From the command line" >}}
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
{{< /tab >}}
|
||||
{{< /tabs >}}
|
||||
|
||||
### Persistence
|
||||
|
||||
If you decide to disable analytics for an installation, your choice is persisted in the registry and honoured across future upgrades and uninstalls.
|
||||
|
||||
However, the key is removed when Docker Desktop is uninstalled and must be configured again via one of the previous methods.
|
||||
|
||||
The registry key is as follows:
|
||||
|
||||
```powershell
|
||||
SOFTWARE\Docker Inc.\Docker Desktop\DisableMsiAnalytics
|
||||
```
|
||||
|
||||
When analytics is disabled, this key has a value of `1`.
|
||||
|
||||
## Additional resources
|
||||
|
||||
- [Explore the FAQs](faq.md)
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
title: Use Intune
|
||||
description: Use Intune, Microsoft's cloud-based device management tool, to deploy Docker Desktop
|
||||
keywords: microsoft, windows, docker desktop, deploy, mdm, enterprise, administrator,
|
||||
---
|
||||
|
||||
Learn how to deploy Docker Desktop using Intune, Microsoft's cloud-based device management tool.
|
||||
|
||||
1. Sign in to your Intune admin center.
|
||||
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**.
|
||||
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](install-and-configure.md) for examples on the changes you can make.
|
||||
|
||||
> **Tip**
|
||||
>
|
||||
> It's recommended you configure the Intune deployment to schedule a reboot of the machine on successful installs.
|
||||
>
|
||||
> 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`.
|
||||
{ .tip }
|
||||
|
||||
7. Complete the rest of the tabs and then review and create the app.
|
||||
|
||||
## Additional resources
|
||||
|
||||
- [Explore the FAQs](faq.md).
|
||||
|
|
@ -1160,6 +1160,16 @@ Manuals:
|
|||
title: Understand permission requirements for Mac
|
||||
- path: /desktop/install/windows-install/
|
||||
title: Windows
|
||||
- sectiontitle: Use the MSI installer {{< badge color=violet text="Early Access" >}}
|
||||
section:
|
||||
- path: /desktop/install/msi/
|
||||
title: Overview
|
||||
- path: /desktop/install/msi/install-and-configure/
|
||||
title: Install and configure
|
||||
- path: /desktop/install/msi/use-intune/
|
||||
title: Use Intune
|
||||
- path: /desktop/install/msi/faq/
|
||||
title: FAQs
|
||||
- path: /desktop/windows/permission-requirements/
|
||||
title: Understand permission requirements for Windows
|
||||
- path: /desktop/install/linux-install/
|
||||
|
|
|
|||
Loading…
Reference in New Issue