Skip to content

Linux WSL Setup

The Integration Platform development environment requires the use of several third-party products that are used to implement various parts of the overall solution. These include

  • Redpanda (an implementation of Apache Kafka)
  • MinIO (an S3 storage provider)
  • SMTP4Dev (an SMTP server that can be used in development environments to test the email messaging capabilities of various Integration Platform tools)

To simplify the configuration of the development environment, these tools are provided in a preconfigured Linux VM that can be downloaded and run locally using the Windows Subsystem for Linux (WSL).

Installing Windows Subsystem for Linux

If you don't already have Windows Subsystem for Linux installed on your Windows development system, follow these steps to install it:

  1. Open an elevated PowerShell window.

  2. Check that the Virtual Machine Platform is enabled, and if not, enable it:

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

  3. Check that the Windows Subsystem for Linux optional Windows component is enabled, and if not, enable it:

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

  4. Install WSL without a Linux distribution:

    powershell wsl --install --no-distribution

This installs the Microsoft Store version of WSL, enables prerequisites like VMP as needed, and skips installing Ubuntu (or any distro). If Microsoft Store is blocked, use

``` powershell
wsl --install --no-distribution --web-download  
```

This pulls from Microsoft’s online source instead of the Microsoft Store.

The installer may enable features and then ask for a reboot. Restart Windows if prompted.

  1. Make sure new distros will default to WSL 2 by setting WSL 2 as the default architecture for any distro installed later:

    powershell wsl --set-default-version 2

  2. Update WSL components to the newest build:

    powershell wsl --update

If the Microsoft Store is blocked and you need a direct download, you can use

``` powershell
wsl --update --web-download
```

  1. Verify the install (and that no distro is present):

    powershell wsl --version      \# Shows WSL version, kernel, WSLg, etc. wsl --status       \# Quick status overview wsl -l -v          \# Lists installed distros (should say none)

These commands confirm WSL is installed and current and that you have no distributions installed yet.

That’s it — WSL 2 is now installed and up to date, with no Linux instance on the machine until you explicitly add one later. Now proceed with Downloading and Installing the SIPVM Linux VM.

Updating Windows Subsystem for Linux

If you already had Windows Subsystem for Linux installed, ensure that you have the latest version:

  1. Update WSL components to the newest build:

powershell wsl --update

If the Microsoft Store is blocked and you need a direct download, you can use

powershell wsl --update --web-download

Downloading and Installing the SIPDEV WSL VM

  1. Decide where you want to store the files for the Linux (WSL) distro and create a directory to host the files. We suggest something like C:\VM\WSL\SIPDEV.

The WSL machine's disk image is stored in the Synergex SharePoint server and, assuming you have been granted access, you can downloaded it here. The download is a single 7-Zip archive (SIPDEV.7z) and at the time of this writing is about 1 GB in size.

  1. After downloading, extract the .7z file to your chosen location and then delete the .7z file. You should be left with a file called sipdev.tar.

  2. Using a command prompt window in the chosen location, execute import.bat to import the WSL instance from the tar file.

Once the import is complete, you can delete the tar file.

  1. The new WSL VM is named sipdev and should now show up in Windows Terminal, or you can launch it manually:

powershell wsl -d sipdev

On startup you should be automatically logged in to the admin account, but if for any reason that fails you can login with

powershell wsl -d sipdev -u admin

The password is p@ssw0rd.

Starting the WSL VM at Boot Time

If you'd like the WSL virtual machine to be started automatically when you start your development PC, follow these instructions:

  1. Make sure the WSL SIPDEV instance is not running:

powershell wsl --list --running

If necessary, terminate it:

powershell wsl --terminate sipdev

  1. Open the Windows Task Scheduler utility.

  2. Right-click on Task Scheduler Library and select Create Task...

  3. On the General tab:

  4. Enter a name for the task, such as "Start WSL (SIPDEV)".

  5. Under Security options, select "Run whether user is logged on or not" and also "Run with highest privileges."

  6. On the Triggers tab:

  7. Click the New... button to define a new trigger.

  8. In the New Trigger dialog, set the Begin the task option to "At startup."

  9. Click the OK button to close the dialog.

  10. On the Actions tab:

  11. Click the New... button to create a new action.

  12. With action set to "Start a program," set Program/script to

    text wsl.exe

  13. Set Add arguments (optional) to

    text -d sipdev -- bash -c "while true; do sleep 3600; done"

  14. Click the OK button to close the dialog.

  15. Click the New... button to create a second new action.

  16. With action set to Start a program, set Program/script to

    text powershell.exe

  17. Adjusting the path if necessary, set Add arguments (optional) to

    text C:\DEV\SYNERGEX\IntegrationPlatform\windows\WslPortForwarding.ps1

  18. Click the OK button to close the dialog.

  19. By default the task will run only when the PC is on AC power. If you want to change that, on the Conditions tab, configure the options under Power to meet your requirements.

  20. On the Settings tab, uncheck the "Stop the task if it runs longer than" option.

  21. Click the OK button to create the task and then reboot your system. After logging in, check that the VM instance is running:

    cmd wsl --list --running