Remote Development with Docker WSL2 and Visual Studio Code

If you are a Windows user, this tutorial will help you set up a docker container in a Linux environment and connect to it through a local installation of Visual Studio Code. If you need to run Docker for Linux but do not want to use a virtual machine (VM) or do dual-booting, this set-up is ideal for you.

Set Up WSL2

To gain access to a Linux machine we will be using WSL2 — but what is WSL2 and why are we using it?

WSL stands for Windows Subsystem for Linux. Traditionally to gain access to a Linux machine Windows users would have to install a virtual machine such as VirtualBox or do a dual-boot setup. Both options require allocation of resources —such as CPU and storage — but WSL removes this overhead. As the name implies, WSL2 is an upgraded version of WSL aiming to increase file system performance and add full system call functionality.

Install WSL2

The first step is to install WSL2. More detailed installation instructions can be found through Microsoft’s documentation, but the following summarizes the steps.

1. Open a Powershell terminal as Administrator
2. Run the following to enable WSL.

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

2. Next, enable the Virtual Machine Platform feature.

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

3. Restart your machine.

4. Download the WSL2 Linux kernel update package and run it.

5. Set WSL2 as your default version.

wsl --set-default-version 2

6. Install a Linux distribution from the Microsoft Store. In this tutorial we are using Ubuntu 18.04 LTS.

7. Return to your Powershell terminal. After your Linux distribution is installed, check its WSL version by running the following command.

wsl --list --verbose

In the image above the WSL version for Ubuntu 18.04 is 1. If the WSL version of your installed distribution is 1 update it to WSL2 by running the following.

wsl --set-version <distribution name> 2

Now, verify that the WSL version has been updated to 2.

wsl --list --verbose

Install Docker via Docker Desktop

Before we can create a container, we need to set up Docker on our new Linux host. We will be using Docker Desktop as it provides an easy-to-use development environment for running Docker.

1. Install Docker Desktop for Windows and open the application through the Windows start menu. Under Settings -> General ensure ‘Use the WSL 2 based engine” is selected.

2. Under Settings -> Resources -> WSL INTEGRATION ensure that the Linux distribution you downloaded (Ubuntu 18.04 in our case) is enabled.

3. Open the Linux distribution you downloaded earlier from the Microsoft Store from the Windows start menu. When you open the application a terminal window will appear.

To confirm that docker has been installed run:

docker --version

4. Now run hello-world to confirm Docker is installed correctly.

docker run hello-world

If your installation is working correctly you will see the following output:

Create a Docker Container

Now that we have docker installed, let’s create a container. First we need to create an image (a template used to build our container). Although we can build our image manually the most efficient method is to use a Dockerfile as it automates the process. It is a simple text file that contains a list of commands needed to assemble the image.

1. First create a directory called ‘myproject’ where our project repository will be stored, and navigate into it.

mkdir myproject && cd myproject

2. Now create a Dockerfile using the nano text editor. To install nano run the following commands.

sudo apt update
sudo apt install nano

Now create the Dockerfile.

nano Dockerfile

The nano text editor will open the Dockerfile you just created. There are many ways to create a Dockerfile to specify your needs, but we will create a simple one. Fill it with the following.

FROM python:3 # the base image 
WORKDIR /<username>/myproject # set the project directory
COPY . . # copy all the project files to the container

Use CTRL + X and CTRL + Y to exit the editor and save the file.

4. Now that we have our Dockerfile let’s use it to create our image. We will run the docker build command with the -t option to add a tag.

docker build -t <username>/myproject .

5. Verify that the image is built correctly.

docker images

You should see your image listed, with <username>/myproject under the REPOSITORY field.

6. Now create a container by running the image. Take note of the image id displayed from the previous step, and use it in the following command.

docker run -i -t <image id> /bin/bash

If your image starts properly you should enter the docker container as the root user.

7. Open a new terminal window and run

docker ps

All running containers will be listed. Verify that your container is running by finding your image’s id. Take note of the name Docker has assigned to your container. In the example above it is ‘dazzling_mendel’.

Set Up Remote Development in Visual Studio Code

Now that we have our container running we need an IDE. We will be using Visual Studio Code as it offers extensions for remote development.

1. Install Visual Studio Code for Windows.

2. Open Visual Studio Code and install the Remote Development extension. This will allow us to connect to the container running on our Linux host.

2. If Remote Development is installed a green icon will appear in the bottom left-hand corner. Click on it to connect to our container.

3. A set of options will appear. Click on ‘Attach to Running Container’.

4. A list of running containers will be displayed. Click on the one you created. You can identify it by the container name we found earlier by running docker ps. In this example our container name is ‘dazzling_mendel’.

When you select the container you wish to connect to a new Visual Studio Code window will open. In the bottom left corner the green bar will display the name of your container.

Congratulations — you have finished setting up your development environment! You can now edit files directly within your docker container on your native installation of Visual Studio Code.

Working in Your New Development Environment

Now that the development environment setup, here are some basic tips on where to get started.

To open your project folder click on File -> Open Folder and search for /<username>/myproject.

The window will reload and open your project folder, containing the Dockerfile we created earlier. You can add your project files here.

To access the command line of your container directly within Visual Studio Code, open a new terminal. Just go to Terminal -> New Terminal.

If you want to open local files outside of your docker container you can still do that. Just navigate to File -> Open File -> Show Local.

To stop your docker container run docker stop with your container name (dazzling_mendel in this example).

docker stop <container name>

To verify that your container has exited run.

docker ps -a

A list of all containers (running or not) will be displayed. The status of your container should be ‘exited.’

To start your container again, run the following.

docker run <container name>

Conclusion

Now you know how to set up a Docker container on a Linux host and connect to it remotely through Visual Studio Code — all without allocating resources to VirtualBox or a dual boot setup. The next step is to start developing your application and installing any dependencies on your isolated docker container. Happy coding!