Overview

The Windows Subsystem for Linux (WSL) is a compatibility layer that allows Linux applications to run directly on Windows 10/11 and Windows Server 2019 or later. To run Linux applications on top of the WSL layer, a Linux distribution must be installed on WSL. A prepared Linux image (based on Ubuntu 20.04.5 LTS) containing all the required Linux tools for SeqSphere+ can be installed via a menu command.

By installing WSL and the adapted Linux, SeqSphere+ users on Windows can benefit from Linux based applications that are distributed together with SeqSphere+:

Once WSL has been successfully installed on client computers, these features will automatically appear in the SeqSphere+ pipeline script settings and tools menu (except for the AMRFinderPlus, SISTR, MOB-suite and MobileElementFinder functionality that come linked to task templates).

Installation of WSL

Button16 Important.png Important: For Windows Server 2019 the automatic installation described in this chapter cannot be used. The installation must be done manually as described in the Windows Server 2019 section below.

WSL must first be enabled, before a Linux distribution can be installed on it. There are two different versions of WSL: WSL 1 and WSL 2. In principle both versions can be used for SeqSphere+. However, we recommend for Windows 10 using WSL 1 and for Windows 11 using WSL 2 for best compatibility.

Enabling WSL

Enabling WSL requires administrative privileges and must be done once for each computer that has a SeqSphere+ client installed.

Enabling WSL 1 (recommended for Windows 10)

Windows 10 Features dialog for enabling WSL 1

For enabling WSL 1 on Windows 10 the Windows Subsystem for Linux feature must be activated using the following steps:

  1. Right-click on the Windows Start menu icon, choose Search and type Windows Features. Select the top entry (category Control panel) to enable or turn off Windows-Features. The Windows-Features dialog will be opened.
  2. Select in the upcoming dialog the check box for Windows Subsystem for Linux from the bottom of the list and press the OK button. Applying the changes may take a few minutes. Finally, press the Restart now button to reboot the computer.

Enabling WSL 2 (recommended for Windows 11)

Windows 11 Features dialog for enabling WSL 2

Button16 Important.png Important: WSL 2 requires virtualization technology on the computer. For AMD CPUs this technology is called AMD Secure Virtual Machine (AVM-SVM) or AMD Virtualization (AMD-V), for Intel CPUs it is called Intel VTX. Instructions how to enable virtualization technology can be found here: Enable virtualization on Windows 11 PCs

After this, for enabling WSL 2 the Virtual Machine Platform feature must be activated using the following steps:

  1. Right-click on the Windows Start menu icon, choose Search and type Windows Features. Select the top entry (category Control panel) to enable or turn off Windows-Features. The Windows-Features dialog will be opened.
  2. Select in the upcoming dialog the check box for Virtual Machine Platform from the bottom of the list and press the OK button. Applying the changes may take a few minutes. Finally, press the Restart now button to reboot the computer.

Installing Linux distribution

Linux Distribution install dialog
Successful system check after installation

The Linux distribution must be installed for both WSL 1 and WSL 2. The installation must be done once for each Windows user who needs the Windows Subsystem for Linux functions. It requires no administrative privileges.

  1. Start the SeqSphere+ client and invoke in the Help menu Tux.png Install Linux Distribution for WSL.
  2. The Linux Distribution install dialog will be displayed.
    An installation path must be selected. The files for the WSL Linux distribution will be stored in the selected directory. This directory must be empty, and the current user must have read and write access to the given directory. Each user on a computer must use an own directory, the Linux distribution cannot be shared between multiple users.
    At least 20 GB free space is required in the installation directory. Note that it is not possible to use an external drive for WSL installation.
    The WSL version that should be used can be selected or the default version can be used. If unsure, select "Default".
    After clicking OK, the latest version of the Linux distribution with all required tools will be downloaded from the Ridom webserver (approx 2.6 GB). After downloading, the downloaded data is unpacked. After unpacking, the Linux distribution is imported into WSL. The import can take some time, up to an hour for slower systems when WSL 1 is used.

    After the import is finished a system check will be run. If all checks succeed with OK, WSL was successfully installed and all tools are working.


Button16 Important.png Important: When the SeqSphere client is uninstalled later from the computer, the Linux installation is not removed automatically. To remove it from the system, start the SeqSphere+ client (before uninstalling it) and invoke in the Help menu Tux.png Install Linux Distribution for WSL. A window will show the information that the Linux distribution is already installed. Click the button Uninstall. The uninstallation step must be done for each Windows user who has installed the Windows Subsystem for Linux functions. It requires no administrative privileges.

Updating from SeqSphere Version 7 or 8

When updating from SeqSphere version 7 or 8, an existing WSL installation is initially used by default. This WSL can still be used for the old functions (e.g. SKESA), but it does not include the tools MOB-suite, MobileElementFinder, and SISTR that are required for some new functions.

To use these new functions, it is necessary to install the new WSL as described above. After the new WSL installation is completed, the old WSL installation is not needed any more, and can be removed (by using the 'Add or remove programs' function of the Windows System Settings or by right click on the Ubuntu app and select 'Uninstall').

Troubleshooting

Corrupted WSL Installation

After a major Windows update has been installed, it can happen that an existing WSL is not correctly working any more.

In those cases invoke again in the Help menu Tux.png Install Linux Distribution for WSL. Then reinstall the Linux Distribution.


Manual Uninstallation of WSL Linux distribution

To manually uninstall the WSL Linux distribution used by SeqSphere use the following steps:

  • Step 1: Start Windows Command Line cmd
  • Step 2: Enter: wsl --unregister ridom_ubuntu

This can also be used to uninstall the WSL Linux distribution after the SeqSphere Client has already been uninstalled.


Manual Installation of WSL on Windows Server 2019

For Windows Server 2019 the automatic installation of WSL that is implemented in SeqSphere cannot be used. However, WSL can be installed manually using the following these steps:

Button16 Important.png Important: When WSL starts up and the new Linux username is defined, be sure to enter "ridom" as username.
  • Step 2: In the newly started Linux, download the Ridom Ubuntu distribution archive file by typing
cd ~
wget https://www.ridom.de/download/wsl/ridom_ubuntu.tgz
  • Step 3: Extract the miniconda tools of this archive file by entering the command:
cd /
tar -xvzf /home/ridom/ridom_ubuntu.tgz ./home/ridom
This will extract the miniconda tools to the user-directory in WSL. The extraction may take some time.
  • Step 4: Exit wsl by typing exit. Restart the SeqSphere client and run Help | Run System Test for testing the installation.

Manual Installation of WSL on Windows 10, Windows 11 and Windows Server 2022

To install the Linux distribution for multiple users or on multiple computers a manual installation can be done. The following steps allow to download the Linux distribution only once and share the downloaded file for multiple installations. However, the installation process still needs to be repeated for each user. The installation directories cannot be shared between multiple users.

  • Step 2: Extract the .tgz file to a .tar file, e.g. by using the program 7zip. Rename the extracted tar-file to ridom_ubuntu.tar.
  • Step 3: Switch to the user account for which WSL should be installed.
  • Step 4: Create a directory for the WSL-files, e.g. C:\wsl_username. Each user must have a separate directory.
  • Step 5: Open a command line and change the current directory to the directory of the extracted file. Then import the extracted tar file into WSL using
    wsl --import ridom_ubuntu C:\wsl_username ridom_ubuntu.tar --version 2
    Instead of C:\wsl_username use the directory created in the previous step.
    Use either --version 1 or --version 2 depending on the WSL version that should be used.