Skip to main content

Installation on Windows

Before you start​

You will need to have the following installed or configured:

  • Windows 10
  • Administrator Rights on the machine
  • Access rights on the “Ubuntu 20.04 LTS” and “Windows Terminal” apps in the “Windows App Store”

Install Windows Terminal​

The default terminal application that ships with Windows is not great. Working with Conveyor involves interaction with the shell. We therefore recommend that you install Windows Terminal from the Windows App Store. Windows Terminal supports the legacy Command shell (cmd.exe), Powershell shell (powershell.exe) and WSL shells.

note

If you already use and have a strong preference for another terminal, such as ConEmu, feel free to use this terminal instead. A terminal with native WSL integration is preferred.

Install WSL and a Linux distribution​

To get started with WSL, you will need to enable the WSL Windows component, install Microsoft's Linux kernel and install a Linux distribution from the Windows Store. The official WSL installation guide contains detailed installation instructions.

  • In step 6 of the instructions, we recommend Ubuntu 20.04 as your Linux distribution of choice. Others should also work, but this is the only supported distribution at this time.
  • If you don't know that you are running a preview release of Windows, you almost certainly are not. You should follow the "manual installation" instructions. We do not recommend switching to a preview release of Windows to run Conveyor.
  • WSL can be installed on up-to-date installations of Windows 10 version 1903 and higher. Older Windows versions are not supported. Click here to learn how to check which version of Windows you are running.

After installation:

  • Be really sure that your distribution is configured to run on WSL version 2. Verify this by running wsl --list --verbose in Command shell or Powershell; the line for Ubuntu-20.04 should list 2. The official installation guide details how to change WSL versions of existing distributions.
  • We recommend setting WSL 2 as the default WSL version. You can do this by running wsl --set-default-version 2.
  • WSL 2 relies on virtualization and HyperV. You may run into issues if you've disabled virtualization in your system's BIOS, or if you use other virtualization software such as VMWare or Virtualbox.

Browser authentication​

Running conveyor auth login should open a browser windows as part of the login flow. Normally, this should work out of the box on WSL as well, but we've observed a few instances where this is not the case. In case your browser window does not open as part of the login flow, you can follow these steps to fix the issue.

  1. Ensure that wslu is installed. Executing the command wslsys -R should print the Linux distro you are using, ideally Ubuntu 20.04 LTS.
  2. If wslu is installed, but your browser is still not opening, you should set the BROWSER environment variable in WSL. Running the following command should do the trick: echo "export BROWSER=wslview" >> $HOME/.bashrc. Don't forget to reload your configuration afterward by running source $HOME/.bashrc.
  3. The conveyor auth login command should now be able to open your browser.

Install Docker for Windows​

We recommend installing Docker by installing Docker Desktop on Windows with the WSL 2 engine and WSL integration. This will make Docker available both to Windows and inside your WSL distributions. However, Docker Desktop licencing has changed. After January 31, 2022 companies can choose to either pay a minimal licence pay or use an alternative means to install docker on their machine.

As an alternative, you can install Docker Engine in WSL 2. This is free.

Docker desktop​

The official Docker Desktop on Windows installation instructions guides you through the steps. Before starting the installation, read the following remarks:

  • It is vital that Docker is available within your WSL distributions. Whenever you get to choose, choose "Linux containers" or "WSL 2" over "Windows containers" or "HyperV".
  • If you already installed Docker using Windows containers, you should be able to switch from Windows containers to WSL/Linux containers from the Docker settings menu. Select the gear wheel in the bar at the top of the Docker window to enter the settings menu, then select the option "Use the WSL 2 based engine".
  • During the installation, you need to select the option of WSL 2 components.
  • It can occur that during installation, a pop-up shows up with the message: "WSL 2 installation is incomplete". In this case, you will need to download and execute the required WSL update.

After installation​

  • Ensure that the Docker distribution is configured to run on WSL 2 and not WSL 1. Open a Command shell or Powershell shell (e.g. from the Windows Terminal application) and run wsl --list --verbose; the lines for docker-desktop and docker-desktop-data should list 2. If this is not the case, run wsl --set-version docker-desktop 2 and wsl --set-version docker-desktop-data 2.
  • Enable WSL integration. Open up the Docker settings by clicking the "gear" wheel in the top bar of the Docker window, then select Resources. Ensure that integration with your Ubuntu-20.04 distribution is enabled, and press Apply & Restart.

Docker Engine​

You can follow the instructions here with one exception. The exception is that systemd services do not automatically start up on WSL 2. So you have to run sudo service docker start after every restart.

Install Conveyor​

You can now just follow the Linux instructions to install Conveyor. This is the easiest way to install Conveyor on WSL 2.

Install Visual Studio Code & extensions​

note

This is optional and not required if you want to skip this please continue here

If you try to run conveyor in the Command shell or the Powershell shell, it will not be recognized. This is because it lives inside the Ubuntu-20.04 environment. The same is true for everything else you install inside your WSL distribution (Git, Python, ...). One of the challenges of working with WSL is that you always have to deal with two different systems and filesystems: the Windows system and its filesystem and the WSL system and its filesystem.

info

Inside WSL, you can find the root of your Windows filesystem at mounted at /mnt/c. Inside Windows, you can find the root of your WSL filesystem as a network mount at \\wsl$\Ubuntu-20.04.

Accessing the WSL filesystem from Windows and the Windows filesystem from WSL is slow, and the Windows filesystem lacks support for Linux file permissions. We strongly recommend that you install your WSL applications inside the WSL filesystem.

We consider the WSL environment superior to "native" Windows for most development work. To work around the two-systems "split brain" problem, we therefore recommend you to install and run all your code and dependencies inside the Ubuntu-20.04 environment. This allows you to work in the same way as on a native Ubuntu system, with very comparable performance.

You can run graphical applications inside the native Linux system. Unfortunately, this is not always stable, but you can run Visual Studio Code as an alternative. Visual Studio Code is WSL-aware, and allows you to run the graphical front-end on Windows, while running everything else (the backend) inside the WSL environment.

  1. Download and install VS Code
  2. Install the following recommended extensions:

From your Ubuntu shell, navigate to the directory you want to open and launch Visual Studio Code using code .. Some additional information can be found here.