App Layering

Docker

March 31, 2025

Contributed by:

To install the App Layering service, you deploy the appliance to a virtual machine on your hypervisor.

How To Install WSL and Docker

These instructions apply to all App Layering image types but are primarily intended for use with full UserLayer deployments of non-persistent VDI desktops. See related guidance at Manual installation steps for older versions of WSL. For App Layering, these instructions will provide WSL and Docker as a base for domain users in a deployed VDI pool of VMs.

Domain users attempting to use WSL and/or Docker must be members of the domain admin group. Using a separate admin account on behalf of a domain user during the user portion of these steps will not work.

Other pre-requisites exist that are not covered below, such as ensuring the virtual machines have nested virtualization enabled (if you plan to use WSL2), and having a computer GPO present to create and populate a ‘docker-users’ group to which users need to be a member. Windows 10/11 versions should be current with the version of WSL/Docker being used.

Step-by-step guide - Docker / WSLv2 (Win 10 or 11)

In a new app layer (preferred), or os-layer revision, as admin:

a. dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

b. dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

c. Disable wsl auto updates

i.  reg add hklm\software\Microsoft\Windows\CurrentVersion\Lxss /t REG_DWORD /v AutoUpdate /d 0 /f

d. Reboot to install features, then log back in

e. Download and install the latest stable WSL release from Microsoft/WSL

i.  Move the download to a place where users can access it later (do this BEFORE installing it)

ii.  Install of WSL must be done from the same folder location that users will be using

    1.  Do not use the wsl --install command

    2.  Sample install command: 'msiexec -i wsl.2.3.26.0.x64.msi /L*V wsl-install.log'

    3.  Suggestion: create a "UserInstall.cmd" script containing a similar msiexec command to be used in step 2.a

iii.  If an older WSL installation is present it should be uninstalled first (using 'msiexec /x' to fully remove it)

iv.  It is not recommended to install a specific distro into the app layer. Users can choose a distro later if they wish to.

v.  Do not remove the WSL .msi installer from this folder. Users will need to apply this exact .msi during their setup later.

f. Use ‘wsl –version’ to verify wsl is working

g. (Optional) add a .wslconfig to the Default user profile

i.  Existing users would need to copy this to their own profile

ii.  The default network operation for wsl2 should be established in a file named .wslconfig and placed in \Users\Default.

    1.  .wslconfig contains two lines: '[wsl2]' and 'networkingMode=mirrored' (without quotes, case as shown)

    2.  Only new users-layer users will automatically have this file copied to their profile area

    3.  Place a copy of the .wslconfig file in the WSL installer location for existing users to copy

h. Download and install Docker

i.  See [Install Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/)

ii.  Docker will log out

iii.  Log back in (Docker will start itself, but this can be ignored now)

iv.  'Accept' terms and Close the Docker Desktop sign-in window

v.  In the latest releases of Docker, an error popup may appear at this time (see exact text of this popup in Info section below). Docker now seems to demand the presence of an installed distro. This popup can be dismissed and ignored, and Docker will exit due to this. That too can be ignored at this point in the installation steps. i.  Finalize the layer (for app layer, must be included in the image; not delivered elastically)

For each user logging in:

a. Locate and run the WSL installer (saved from step 1.e.i)

i.  This will be a fast and minimal install that only sets up reparse-points for the user

ii.  This is a one-time install for each user, but can be used again if wsl problems arise

iii.  Do not copy the wsl .msi to an alternate location before installing it (e.g., 'cd \WSL' and repeat the original/similar msiexec command)

b. Install a private distro using powershell: (example using the ubuntu-1604 distro)

i.  Invoke-WebRequest -Uri [https://aka.ms/wsl-ubuntu-1604](https://aka.ms/wsl-ubuntu-1604) -OutFile ~/Ubuntu.zip -UseBasicParsing

ii.  mkdir ~/distros

iii.  Expand-Archive ~/Ubuntu.zip ~/distros/Ubuntu

iv.  Run the installer as admin ~/distros/Ubuntu/ubuntu*.exe (exact name is version specific)

v.  Provide a username and password you will use to log into wsl, and complete the install

vi.  When this completes, update the distro in the distro-specific fashion ( sudo apt-get update; sudo apt-get upgrade )

vii.  (Optional) create a desktop shortcut to the installed distro's main application

viii.  Leave your distro window running for the remaining steps

c. Launch Docker Desktop from start menu

i.  Allow Docker to initialize and start the docker engine

ii.  Important: Docker needs to be made aware of your distro

    1.  In Docker, go to 'Setting->Resources→WSL Integration'

        a.  Enable the 'additional distro' that matches yours
            
        b.  Disable the 'default WSL distro' selection

iii.  Also, you can control Docker auto-startup in 'Settings→General'

iv.  Remember that your distro/WSL session needs to be started before the Docker engine can start successfully

Upgrading

Any time an upgraded WSL/Docker App Layering is rolled out, each affected user will need a repair operation using the prior WSL/Docker layer.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Docker

March 31, 2025

Contributed by:

Docker

How To Install WSL and Docker

Step-by-step guide - Docker / WSLv2 (Win 10 or 11)

Upgrading

In this article