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+:

• SKESA (fast de-novo assembling)
• SPAdes (fast de-novo assembling) [Requires WSL 2!]
• NCBI AMRFinderPlus (resistance geno-prediction)
• Mash (species identification and species contamination check, Mash plasmid databases²⁾)
• BWA-MEM (fast read mapping)
• iVar (SARS-CoV-2 tiled amplicon raw reads processing)
• Illumina sequencing run details (reading Illumina InterOp files)
• iVar (SARS-CoV-2 tiled amplicon raw reads processing)
• SISTR (S. enterica geno-serotyping)
• MOB-suite (chromosome and plasmids detection)
• MobileElementFinder
• FastANI (whole genome average nucleotide identity)
• pyGenomeViz (genome visualization)
• Chopper (Long read preprocessing)¹⁾
• Rasua (Long read preprocessing)¹⁾
• FiltLong (Long read preprocessing)¹⁾
• Flye (Long read assembling)¹⁾
• Raven (Long read assembling)¹⁾
• Medaka (Long read assembly polishing)¹⁾

¹⁾ Only required and available for ONT Data Assembly Module

²⁾ Only required and available for Long-read Data Plasmid Transmission Analysis Module

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).

Hints: Due to limitations in WSL, Linux applications running in WSL cannot access network drives. Working with files from network drives therefore will fail for applications that are started via the Tools menu. However, when the pipeline is run, the input files are copied to a temporary directory on the local computer. Therefore it is no problem to use a network drive as a source for read files together with Linux applications in pipeline mode.

Installation of WSL

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)

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)

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

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 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. Installation on external hard drives or network drives is not possible. Each user on a computer must use an own directory, the Linux distribution cannot be shared between multiple users.
   At least 35 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 4.1 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.

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 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 old SeqSphere Versions

When updating from older SeqSphere versions, an existing WSL installation is initially used by default. This WSL can still be used for the old functions, but may not include the tools and versions that are required for some new functions.

Updating from SeqSphere Version 9

To use the new functions, an existing Ridom WSL distribution must be updated.

1. Start the SeqSphere+ client and invoke in the Help menu Install Linux Distribution for WSL.
2. A message The Linux distribution is outdate and must be reinstalled will be displayed.

The WSL version that was used for the previous installation is pre-selected. Click OK to download and install the new Ridom Linux distribution.

Updating from SeqSphere Version 8 or older

To use the new functions, it is necessary to install the Ridom WSL distribution as described above. After the installation of the Ridom WSL distribution 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 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:

• Step 1: Install Ubuntu 20.04 using the steps described at the Windows Server Installation Guide

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.

• Step 4: If the Test Testing Windows Subsytem for Linux (WSL) fails please download the file File:Set WSL Command.xml. This file changes the way SeqSphere starts WSL. Use File > Open File(s) in the SeqSphere client to open this file. Then restart the SeqSphere client and start the System Test again.

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 1: Download the Ridom Ubuntu distribution archive from https://www.ridom.de/download/wsl/ridom_ubuntu.tgz.

• 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.

• Step 6: If multiple WSL distributions are available for a user, the distribution that is used by Ridom SeqSphere must be specified. To do this select Options | Preferences from the menu. A dialog window will open. Select General | Windows Subsystem for Linux in the list on the left side. Then make sure that ridom_ubuntu is set as WSL distribution.