Skip to content
Disguise User Guide

Machine Setup

These instructions are for the initial setup of each machine that is intending to run Porta On Prem.

WSL Setup and Ubuntu Installation

  1. On a device that has internet access, download:

  2. Copy the downloaded files to the machine being installed

  3. Ensure that the machine has installed any pending Windows updates

  4. Open the Windows start menu, search for Windows Features, and select Turn Windows features on or off

  5. Enable the following features if they are not checked already:

    • Virtual Machine Platform
    • Windows Subsystem for Linux

  6. Reboot the machine after enabling these features

  7. In the files you downloaded and transferred to the machine, double-click wsl_update_x64_XXXXXX.cab to extract the WSL2 kernel .msi file

  8. Run wsl_update_x64.msi to install the WSL2 kernel update

    • If your machine is already more-up-to-date than 5.10, this step may not work. Continue to the next step.

  9. Open powershell as administrator

  10. In powershell, run dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

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

  12. Double-click wsl.2.0.14.0.x64.msi to update WSL to version 2.0.14

    • If your machine is already more-up-to-date than 2.0.15, this step may not work. Continue to the next step.

  13. Reboot the machine

  14. Open powershell as administrator

  15. Run wsl --set-default-version 2

  16. Check your WSL version with wsl --version (or wsl --status)

    • the WSL version should be 2.0.14 or higher
    • the Kernel version should be 5.10.102.2 or higher

  17. Install the Porta Ubuntu image

    1. Run wsl --shutdown

    2. Run wsl --import Ubuntu-20.04 Ubuntu %USERPROFILE%\Downloads\Ubuntu2204-WSLimage.tar

      • Replace %USERPROFILE%\Downloads\Ubuntu2204-WSLimage.tar with the path to the downloaded Ubuntu WSL image, if needed

    3. The import may take a few minutes to finish

    4. The initial WSL ubuntu login will be with the root user. We need to set default user by creating a config file and updating it

    5. Open the WSL command line interface by running wsl in powershell

    6. Run:

      Terminal window
      touch /etc/wsl.conf
      Terminal window
      echo -e "[user] \n default=px" > /etc/wsl.conf

    7. Run exit and in powershell, run wsl --terminate Ubuntu-20.04.

    8. When you open wsl again it should be as the px user

    If you have issues using the Porta image, see the Stock WSL Ubuntu Image Installation section below, then return here to run the following steps after the stock image is installed.

  18. After distro install completes, in powershell, you should see Ubuntu-22.04 listed if you run wsl -l -v --all

    • If you aren’t seeing Ubuntu-22.04 listed, try checking the distro in use by starting WSL and checking the OS version by running wsl in Powershell, and then running cat /etc/os-release. The output should look something like: 
      PRETTY_NAME="Ubuntu 22.04.4 LTS"
      NAME="Ubuntu"
      VERSION_ID="22.04"
      VERSION="22.04.4 LTS (Jammy Jellyfish)"
      VERSION_CODENAME=jammy
      ID=ubuntu
      ID_LIKE=debian
      HOME_URL="https://www.ubuntu.com/"
      SUPPORT_URL="https://help.ubuntu.com/"
      BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
      PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
      UBUNTU_CODENAME=jammy

  19. Reboot the machine

  20. Reopen powershell as administrator

  21. Double-check your install: wsl --status, you should see:

    • Default Distribution: Ubuntu-22.04
    • Default Version: 2
    • If you receive “WSL2 is not supported with your current machine configuration” then you need to enable virtualization in the BIOS. This process will vary depending on your machine.

  22. Make sure Ubuntu is using WSL2 by running wsl -l -v --all this should look something like:

    NAME                   STATE           VERSION
    * Ubuntu-22.04           Running         2

  23. Ensure Ubuntu is used as the default distro by running this command in Powershell:

    • wslconfig /s Ubuntu-22.04

  24. You can confirm by running wsl --status again, or wslconfig /l

  25. Now you can move on to the Docker installation.

For more details, see the Official Microsoft WSL manual install instructions.

Stock WSL Ubuntu Image Installation

  1. Rename the Ubuntu AppxBundle extension from .AppxBundle to .zip
  2. Extract this zip archive
  3. Inside the extracted folder, use the file with the name ending in _x64.appx in the next step (likely Ubuntu_2204.1.7.0_x64.appx)
  4. Open Powershell as administrator, navigate to the folder containing the .appx and run the following command in that directory, where app-name is the name of the Linux distribution .appx file: Add-AppxPackage .\Ubuntu_2204.1.7.0_x64.appx
  5. Once the Appx package has finished, you can start running the new distribution by running the following steps (The command wsl -l will not show that the distribution is installed until this step is complete):
    1. Add your Linux distribution path to the Windows environment PATH (C:\Users\Administrator\Ubuntu in this example), using PowerShell:
      Terminal window
      $userenv = [System.Environment]::GetEnvironmentVariable("Path", "User")
      [System.Environment]::SetEnvironmentVariable("PATH", $userenv + ";C:\Users\Administrator\Ubuntu", "User")
    2. In powershell, run ubuntu2204.exe. This will begin installing the Ubuntu 22.04 distro and prompt for user setup.
    3. When prompted for a username and password, enter a new username and password (this user will have sudo aka admin permissions)
      • The username must contain only lowercase letters, underscores, and dashes
      • Do not proceed with the root user, this is a security risk and will cause issues with the installation
  6. Resume the instructions at Step 18 above in the WSL Setup & Ubuntu Installation section.

Docker

Download and install Docker Desktop for Windows, version 4.28.0:

Follow the installer instructions for WSL2 backend and, when prompted in docker, ensure the Use WSL 2 instead of Hyper-V option on the Configuration page is selected.

After installation is complete, open Docker Desktop and ensure it is running, then proceed with the following:

  1. Set Docker Desktop to start on login

    • In the top right menu bar, click the gear icon to open settings
    • Select the left sidebar’s “General” tab to pull up the General settings
    • Check the box “Start Docker Desktop when you log in”
    • Also Uncheck:
      • Send usage statistics
      • Show CLI Hints
      • SBOM Indexing
    • In the bottom right, click “Apply & Restart”
    • Using the inner “X” icon in the top right, close the Settings menu

  2. Disable Resource Saver in Docker Desktop Settings

    • In the top right menu bar, click the gear icon to open settings
    • Select the left sidebar’s “Resources” tab
    • Uncheck the box “Enable Resource Saver”
    • In the bottom right, click “Apply & Restart”

  3. Disable Updates in Docker Desktop Settings

    • In the top right menu bar, click the gear icon to open settings
    • Select the left sidebar’s “Software updates” tab to pull up the updates settings
    • Uncheck the box “Automatically check for updates”
    • Uncheck the box “Automatically download updates”
    • In the bottom right, click “Apply & Restart”

  4. Disable Extensions in Docker Desktop Settings

    • In the top right menu bar, click the gear icon to open settings
    • Select the left sidebar’s “Extensions” tab
    • Uncheck the box “Enable Docker Extensions”
    • In the bottom right, click “Apply & Restart”

  5. Disable Beta Features in Docker Desktop Settings

    • In the top right menu bar, click the gear icon to open settings
    • Select the left sidebar’s “Features in Development” tab
    • Uncheck the box “Enable WASM”
    • Uncheck the box “Enable SOCKS proxy support”
    • In the bottom right, click “Apply & Restart”

  6. Disable Notifications in Docker Desktop Settings

    • In the top right menu bar, click the gear icon to open settings
    • Select the left sidebar’s “Notifications” tab
    • Uncheck ALL items in the list
    • In the bottom right, click “Apply & Restart”

  7. Using the inner grey “X” icon in the top right, close the Settings menu

  8. Set up the Windows user to auto-login

    • A sales engineer, support engineer or IT specialist may need to help with this step

  9. Open the hosts file as administrator in Windows (Located in C:\Windows\System32\drivers\etc)

    • This is often most easily done by opening the start menu and typing notepad to search for the Notepad application
    • Right-click the Notepad application and select “Run as administrator”

  10. Copy & paste the following entries at the bottom of the hosts file and replace each <XXXXXXX MACHINE IP> with the appropriate machine IPs. Save the hosts file as type All files (*.*) (it should have NO file extension).

    <CURRENT MACHINE IP> porta-socket.server
    <MAIN MACHINE IP> porta-db
    <BACKUP MACHINE IP> porta-db-2
    <ARBITER MACHINE IP> porta-db-3
    • NOTE: The IP address required here cannot be 127.0.0.1. It is the IPv4 address for the machine’s current network connection. The IPv4 address can be observed by running ipconfig in Powershell or cmd.exe and looking under the correct network adapter’s (often d3net) value for IPv4.

  11. Add inbound rules to open mysql ports on EACH machine:

    1. In Windows Security —> Firewall & network protection —> Advanced Settings —> Inbound Rules —> Add Rule
    2. Choose “Ports” then hit Next
    3. Choose TCP and add or paste these as specific local ports: 3306,3307,3308,33061,33062,33063
    4. Allow the connection
    5. Apply the rule in all scenarios
    6. Name the rule “Porta MySQL Ports”

Porta On Prem Installation

Now the machine is set up to run Porta On Prem. Follow the Porta On Prem Installation Guide to complete the installation.

Troubleshooting

Installation

For Porta installation troubleshooting, see Installation Troubleshooting

Database Replication

For database troubleshooting, see Group Replication Troubleshooting

wsl --install -d Ubuntu-22.04 gives Error Code 0x80072ee7

WSL/Ubuntu set up will need to be done using the offline steps in the WSL Setup & Ubuntu Installation section above.

WslRegisterDistribution failed with error: 0x80370102

This error may occur when rebooting after wsl --install.
Follow the WSL instructions to enable virtualization in the BIOS, then continue with the installation steps from earlier.

ERROR: CreateProcessParseCommon:711: Failed to translate when running wsl commands

Make sure that Ubuntu was set as a default distro, this error often indicates that Docker’s distro is being used instead of Ubuntu. Though soem commands like wsl -l -v --all still worked.

This error displayed as:

Terminal window
PS C:\Users\administrateur> wsl
<3>WSL (27) ERROR: CreateProcessParseCommon:711: Failed to translate C:\Users\administrateur
<3>WSL (27) ERROR: CreateProcessParseCommon:757 : getpwuid(0) failed 2
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Program Files\WSL
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\system32
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\System32\Wbem
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\System32\WindowsPowerShell\v1.0\
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\WINDOWS\System32\OpenSSH\
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Program Files\dotnet\
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Program Files\Docker\Docker\resources\bin
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Users\administrateur\AppData\Local\Microsoft\WindowsApps
<3>WSL (27) ERROR: UtilTranslatePathList:2866: Failed to translate C:\Users\administrateur\Ubuntu
Processing fstab with mount -a failed.
Failed to mount C:\, see dmesg for more details.
Failed to mount D:\, see dmesg for more details.
Failed to mount C:\, see dmesg for more details.
Failed to mount D:\, see dmesg for more details.


<3>WSL (27) ERROR: CreateProcessEntryCommon:334: getpwuid(0) failed 2
<3>WSL (27) ERROR: CreateProcessEntryCommon:505: execvpe /bin/sh failed 2
<3>WSL (27) ERROR: CreateProcessEntryCommon:508: Create process not expected to return

Docker Desktop - Unexpected WSL error

An unexpected error was encountered while executing a WSL command…

In Powershell (not cmd or WSL), check wsl --status, if you receive “WSL2 is not supported with your current machine configuration” then you need to enable virtualization in the BIOS. This process will vary depending on your machine.

Docker Installation Errors - “wsl update failed” or similar

If you encounter an error regarding WSL updates when installing Docker Desktop, make sure WSL is up to date by following the instructions in the troubleshooting section “Error: 0x8024500c after wsl —update”, then uninstall Docker Desktop and re-install it.

If you continue to encounter errors regarding WSL updates, uninstall Docker Desktop and re-install it, but this time under Configuration, DON’T check Use WSL2 instead of Hyper-V.

Once install has completed, Docker will prompt you to reboot. After reboot, start Docker Desktop again.

Navigate to Settings

Check “Use the WSL2 based engine”, then select “Apply & restart”.

Error: 0x8024500c after wsl --update

Some installs with Windows 10, or without using the Microsoft store, will display this error. Check the current WSL Kernel version by running wsl --version (or wsl --status) in Powershell and checking the entry for Kernel version, which should begin with 5` (we do NOT want WSL Version“, that is different).

If the Kernel version is not greater than or equal to 5.10.102.2, then we will need to manually update the kernel:

  • Visit Microsoft’s update catalog and sort by last updated. As of writing, the latest version is 5.10.102.2.
  • Download the .cab file for the latest version
  • Double-click the .cab file to extract the .msi file within in
  • Run wsl_update_x64.msi to install the WSL2 kernel update
  • Open powershell as administrator
  • In powershell, run dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart to enable the new version
  • Run wsl --set-default-version 2
  • Check your WSL version with wsl --version (or wsl --status)
    • the WSL version should be 2.X.X (start with 2)
    • the Kernel version should be 5.10.102.2

Check the WSL version by running wsl --version (or wsl --status) in Powershell. If the wsl --version and wsl --status commands do not work, try running:

(Get-AppxPackage | ? Name -eq "MicrosoftCorporationII.WindowsSubsystemforLinux").Version

If the version listed is not greater than or equal to 2.0.14, then you will need to manually update WSL by taking the following steps (as listed in Updating WSL 2 without Microsoft Store) :

Download the 2.0.14 WSL app package and msi release from the WSL Releases page in the Github repo. This will be the assets with file extension .msixbundle and .msi.

Run wsl --shutdown and reboot to make sure that WSL is not in use at all.

Start an Administrator PowerShell and run the following (adjust the package name for the latest version you downloaded):

Add-AppxPackage <path.to>/Microsoft.WSL_1.0.0.0_x64_ARM64.msixbundle

If you run into problems regarding windows store, try installing using the .msi file instead.

After installing, check the new WSL version with wsl --version or (Get-AppxPackage | ? Name -eq "MicrosoftCorporationII.WindowsSubsystemforLinux").Version

Reboot the machine