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.
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.
- Be really sure that your distribution is configured to run on WSL version 2. Verify this by running
wsl --list --verbosein Command shell or Powershell; the line for
Ubuntu-20.04should list 2. The official installation guide details how to change WSL versions of existing distributions.
- We recommend setting WSL2 as the default WSL version. You can do this by running
wsl --set-default-version 2.
- WSL2 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.
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.
- Ensure that wslu is installed.
Executing the command
wslsys -Rshould print the Linux distro you are using, ideally
Ubuntu 20.04 LTS.
- In case wslu is not installed, you can follow these install instructions.
- If wslu is installed, but your browser is still not opening, you should set the
BROWSERenvironment 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
conveyor auth logincommand 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 WSL2. This is free.
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.
- 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)
wsl --list --verbose; the lines for
docker-desktop-datashould list 2. If this is not the case, run
wsl --set-version docker-desktop 2and
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.
You can follow the instructions here with one exception.
The exception is that systemd services do not automatically start up on WSL2.
So you have to run
sudo service docker start after every restart.
You can now just follow the Linux instructions to install Conveyor. This is the easiest way to install Conveyor on WSL2.
Install Visual Studio Code & extensions
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 of the Ubuntu-20.04 environment. The same is true for everything else you install inside of 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 filesystem and the WSL system and filesystem.
Inside WSL, you can find the root of your Windows filesystem at mounted at
Inside Windows, you can find the root of your WSL filesystem as a network mount at
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 of 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.
- Download and install VS Code
- Install the following recommended extensions:
From your Ubuntu shell, navigate to the directory you want to open and launch Visual Studio Code using
Some additional information can be found here.