Configuring WSL2 for CAST Imaging v3

Overview

WSL2 (Windows Subsystem for Linux 2) is Microsoft’s second-generation compatibility layer that allows you to run a Linux environment directly on Microsoft Windows without the overhead of a traditional virtual machine. Within the context of CAST Imaging, installation on WSL2 via Docker is not supported for production deployments, however, it can be used if necessary for testing, evaluation, single use, POCs etc.

The configuration instructions provided below are provided as a courtesy and do not imply any official support of CAST Imaging installed on WSL2.
CAST assumes that you will be installing all CAST Imaging components on one single instance of WSL2 - i.e. not a distributed deployment and that you will be accessing the installation from the host Microsoft Windows machine.
The CAST installation script must be run with elevated permissions within the WSL2 environment, i.e. a user in the `sudoers` list.

Requirements

You should follow the requirements listed in:

You should also familiarize yourself with the installation instructions (single machine) in Installation on Linux via Docker.

Process

Step 1 - install WSL2, Linux and Docker Engine

First install WSL2, a Linux distribution of your choice (see the listed distributions in Software requirements) and configure a Linux user and accompanying password - see https://learn.microsoft.com/en-us/windows/wsl/install .

Now install Docker Engine (including Docker Compose) - see https://docs.docker.com/engine/install/ .

Microsoft Windows file system is mounted under /mnt/c within the WSL2 environment.

Docker Engine and systemd

Docker Engine is configured automatically to start/stop with systemd, however if the command systemctl status docker returns the following error:

System has not been booted with systemd as init system (PID 1). Can't operate. Failed to connect to bus: Host is down

… this indicates that systemd is not configured to run when WSL2 starts. To ensure this is the case:

edit the following file within the WSL2 environment:

# /etc/wsl.conf

ensure that the following lines are present and then save the file:

[boot]
systemd=true

restart WSL2 by shutting it down and starting it up again (this must be run from a command prompt in the Microsoft Windows host environment):

wsl --shutdown
wsl

Step 2 - Configure .wslconfig file

Now that WSL2 is up and running, you need to configure it so that CAST Imaging will function efficiently. To do so:

edit the following file on your Microsoft Windows file system (if it does not exist, create it):

%USERPROFILE%\.wslconfig

apply the following settings to ensure optimal performance - adapt to your own host Microsoft Windows machine and environment.

# Settings apply across all Linux distros running on WSL 2
[wsl2]

# Set max VM memory
memory=22GB

# Sets VM virtual processors (cannot be more than the host system)
processors=2

# Sets additional kernel parameters
kernelCommandLine=vsyscall=emulate

# Sets max swap storage space
swap=16GB

# Sets swapfile path location, default is %USERPROFILE%AppDataLocalTempswap.vhdx. Note that this location must already exist on disk.
swapfile=C:\\temp\\wsl-swap.vhdx

# Turn on default connection to bind WSL 2 localhost to Windows localhost
localhostforwarding=true

# Disables nested virtualization
nestedVirtualization=false

# Turns on output console showing contents of dmesg when opening a WSL2 distro for debugging
debugConsole=false

# Enable experimental features
[experimental]
sparseVhd=true
autoMemoryReclaim=dropcache

save the file, then restart WSL2 by shutting it down and starting it up again (this must be run from a command prompt in the Microsoft Windows host environment):

wsl --shutdown
wsl

Step 3 - Proceed with the installation within WSL2

You are now ready to proceed with the installation within the WSL2 environment (using the single machine mode, all components on one machine scenario) as described in: Installation on Linux via Docker, i.e.

obtain the installation media and unzip it within the WSL2 environment
configure the configuration.conf file found at the root of the unzipped installation files, paying particular attention to setting the IMAGING_SERVICES_HOSTNAME variable to use the IP address determined by running hostname -I in the WSL2 environment. For example given the following response, use the first IP address listed (172.19.90.237):

# hostname -I
172.19.90.237 172.17.0.1 172.18.0.1 172.22.238.1

ensure the installation script and imaging-viewer component are executable by running the following commands from the root of the unzipped installation files:

# chmod +x cast-imaging-install.sh
# chmod +x cast-imaging-viewer/imagingsetup

run the single machine installation option using the following command:

# ./cast-imaging-install.sh all

verify the installation by checking Docker containers are running and “healthy” (you should see 12 containers):

# docker ps

check that you can access the installation using a browser on the host Microsoft Windows machine by browsing to the IP address that you defined in the configuration.conf file, in this example:

http://172.19.90.237:8090

finally, refer to Installation on Linux via Docker for post-installation set-up tasks.