Using devcontainers in Microsoft Windows

Table of contents

Using devcontainers in Microsoft Windows

Some useful context

A number of moving parts work together to make it possible to use devcontainers on Windows. It helps to understand how these parts fit together, both when setting up devcontainers and working with them.

A Docker container is a lightweight, standalone, and executable package that includes everything needed to run a piece of software, including the code, runtime, libraries, and system tools. Containers are isolated from one another and from the host system, ensuring that they run consistently across different environments.

Key characteristics of Docker containers include:

Isolation: Containers provide a way to run applications in isolation from each other and from the host system. This isolation ensures that the application’s dependencies and environment do not interfere with other applications.
Portability: Containers encapsulate all dependencies, allowing them to run on any system that has Docker installed, regardless of the underlying hardware or operating system. This makes it easy to move applications between development, testing, and production environments and to run software on local or remote machines.
Efficiency: Containers share the host system’s kernel, making them more lightweight and efficient compared to virtual machines. They can start up quickly and require less memory and storage.
Consistency: Containers ensure that applications run consistently regardless of where they are deployed, as the environment within the container remains the same across different systems.
Scalability: Containers can be easily scaled up or down to handle varying loads, making them ideal for microservices architectures and cloud deployments.

A devcontainer is the implementation of an open-source collection of specifications and tools that use Docker containers to automatically provide the tools, libraries, and settings required to deliver a full-featured development environment specific to your needs. Microsoft Visual Studio Code (VS Code) is tightly integrated with, and can configure & control, devcontainers. G-Cubed models are run using VS Code within a devcontainer so that all of the benefits of Docker containers are available to users of G-Cubed.

Docker containers on Windows are run and managed by software known as Docker Desktop (Docker). Docker Desktop uses either the Windows Subsystem for Linux (WSL 2) backend to run Linux containers or Hyper-V to run Windows containers. For G-Cubed models, Docker must be configured to use the Windows Subsystem for Linux (WSL 2), running the devcontainers as Linux environments. That means that WSL 2 must also be set up on a Windows computer so that it can be used by Docker.

WSL 2 is the implementation of a real Linux environment running in a lightweight virtual machine (VM) which allows you to run Linux executables natively on Windows 10 and later versions without the need for a separate virtual machine or dual booting. WSL 2 is managed and maintained by Microsoft and receives updates through Windows Update. Using WSL 2 the two operating systems (Windows and Linux) run seamlessly side-by-side and concurrently on your machine (whilst it may look like Linux is running ‘in’ your Windows environment, architecturally it is actually running ‘next’ to Windows as a peer and Windows seamlessly provides a bridge across to that environment). For WSL 2 users some applications will be running in Windows and at the same time some of their applications can be running in Linux.

Care needs to be taken to ensure users know which operating system is running which applications.

Microsoft Visual Studio Code (VS Code) is an extremely sophisticated and extensible code editor which we use to edit and run the G-Cubed models. In this particular configuration the VS Code server (the ‘brains’ which manipulates your files, executes the Python code, etc) runs within the devcontainer in the Linux environment, whilst the user interface (front-end) runs ‘remotely’ in the Windows environment.

To summarise, when using a G-Cubed devcontainer on Windows, you need to be actually working within the Linux operating system (Linux) provided by WSL 2. By starting VS Code within Linux, and opening a devcontainer within it, VS Code provides a front end to the devcontainer that is being managed and run by Docker in a virtual machine running Linux. It is very important to first ensure that you are working within the Linux environment before you start VS Code and try to open the devcontainer. This is true when using devcontainers and it is true when setting them up for the first time.

The final requirements for using G-Cubed devcontainers on Windows is Git source code control software. This software enables devcontainers and their associated data and program files to be downloaded from and sync’ed back to GitHub.

Software to install and configure

To run devcontainers on Windows, you need to install and configure:

Windows Subsystem for Linux (WSL 2) to provide the Linux-based hosting
Docker Desktop
Git for Linux on WSL 2
Git for Windows
VS Code on Windows and a number of VS Code extensions.

This software must be installed in the sequence set out below. Each step must be completed before the next step is started. Do not skip any steps.

The entire installation and configuration process should require between 30 minutes and an hour on a modern Windows computer.

Installing and configuring Windows Subsystem for Linux (WSL 2)

The following instructions are based upon the WSL 2 installation instructions.

Wherever you’re asked to open a Windows Command Prompt you can do so by clicking the Windows Start button or by hitting the Windows key on your keyboard, and then typing cmd and hitting ENTER.

To speed this up you can either select the pin to taskbar option before hitting ENTER above, or by right-clicking on the Command Prompt icon in the taskbar after the prompt window has opened and selecting pin to taskbar there.

When you have finished with the prompt you can close it by typing exit (and pressing ENTER) or by clicking the X button on the top-right of the command prompt window.

WSL 2 requirements

You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11.

We require at least WSL 2 be used rather than its predecessor, WSL.

WSL 2 installation steps

Open Windows Command Prompt in administrator mode by clicking the start button, typing ‘cmd’ in the search box, and right-clicking and selecting “Run as administrator”
Enter the following command at the prompt:
```
 wsl --install
```
This will enable the features necessary to run WSL 2 and it will download and install the Ubuntu distribution of Linux by default.

Using WSL 2, you can run a variety of Linux distributions natively on Windows. Microsoft provides a range of distributions through the Microsoft Store, and you can also manually install other distributions.

We recommend using the default Ubuntu Linux distribution provided through the Microsoft Store. These instructions assume that you are using the default Ubuntu Linux distribution. The Linux-related details of some steps are likely to differ if you are using an alternative Linux distribution.
Once the installation has completed, restart your computer.
Once the computer has restarted, reopen the Windows Command Prompt.
Start Linux.

Linux is started from the Windows Command Prompt by running:
```
 wsl
```
If WSL 2 was successfully enabled and a Linux distribution installed, this will trigger the process of setting up your Linux user account.

If there were problems with enabling WSL 2 or installing the Ubuntu distribution, this step may fail with a warning that there is no Linux distribution installed. In that case, follow the WSL 2 installation instructions to ensure that the Ubuntu Linux distribution is installed. This may involve another full restart of your computer.
Set up your Linux user account.

The Linux operating system manages access and security through user accounts. It is no different when using Linux within WSL 2. To create a user account.

That command will start wsl and request you to enter a username and to provide and confirm a password for that user.

Additional information on user account management is available from Microsoft.

This page also provides useful additional information on how to best integrate the Linux operating system into your work practices.
Shut down the Linux environment by opening a Windows Command Prompt and entering the following command:
```
 wsl --shutdown
```
Configure WSL 2 using a .wslconfig file.

The .wslconfig file (note the dot at the beginning of the filename) configures settings globally for all Linux distributions running with WSL 2. The .wslconfig file does not exist by default. It must be created and stored in your Windows user profile folder, typically C:\Users\<YourUsername> where <YourUsername> is your Windows username.

From within Windows (rather than Linux), open a Windows Command Prompt and type (followed by ENTER):
```
 cd %USERPROFILE%
```
This should put you in your user profile folder (the prompt should change to reflect the above naming convention).

Use notepad to create the .wslconfig file:
```
 notepad .wslconfig
```
And add the following content:
```
 [experimental]
 sparseVhd=true
 autoMemoryReclaim=gradual
```
Depending on your machine capability and size you may find that creating, starting and stopping devcontainers takes a long time and consumes significant processor and memory resources. If so you can further tune WSL 2 by adding the following to the .wslconfig:
```
 [wsl2]
 memory=12GB 
 processors=1
```
Adjust the memory size to something less than 50% of the physical memory installed in your computer. 12 GB is required to run the larger model versions (e.g. 6G or 20C). Adjust the number of processors as required, but we recommend no more than 50% of the processors available to your computer.
Update the Linux operating system and software.

When first installed, the Ubuntu Linux distribution tends to be somewhat dated. You should regularly update it. This is done by opening Linux (Open a Windows Command Prompt and enter the command wsl) and then, from within Linux, running the following command:
```
 sudo apt update && sudo apt upgrade -y
```
You will be prompted to enter a password so that the updates can be run with super-user priviledges. Provide the password that you created when you set up the Linux user account in step 6.

You should regularly run this update and upgrade process. We suggest once every 1-2 months.
Set up the ~/github folder on Linux.

The ~/github folder is where your G-Cubed models will be stored.
- Open a Windows Command Prompt.
- Start Linux by running:
```
wsl
```
- Create the ~/github folder:
```
mkdir ~/github
```
- Ensure that the ~/github folder is the current folder when Linux is started by editing the ~/.profile file.
```
code ~/.profile
```
Add the following content to the end of that file:
```
cd ~/github
```
- Log out of Linux by running the command:
```
exit
```
That command will return you to the Windows Command Prompt. When you next log into your Linux environment (wsl), the github folder will be your current folder.

The tilde symbol (~) is an alias for your ‘home’ folder in Linux (which usually looks something like /home/<yourname>).

cd ~ changes your current folder to your home folder from wherever you are.

mkdir ~/newfolder creates newfolder within your home folder.

cd ~/github changes your current folder to the github folder within your home folder from wherever you are.

Installing and configuring Docker Desktop (Docker)

The following instructions are based upon the Docker Desktop backend on WSL 2 documentation.

Requirements

Docker must be installed on Windows and configured to run on WSL 2. This provides a number of significant performance and usability benefits.

A number of Windows system requirements must also be met. Importantly the computer must have at least 4 GB of RAM. It must have a 64 bit processor. Hardware virtualisation must be enabled in BIOS.

Docker installation steps

Download the Docker installer.
Follow the usual installation instructions to install Docker. Depending on which version of Windows you are using, Docker may prompt you to turn on WSL 2 during installation. Read the information displayed on the screen and turn on the WSL 2 feature to continue.
Start Docker from the Windows Start menu.
Navigate to Settings in Docker.
From the General tab, select Use WSL 2 based engine. Because you have installed Docker Desktop on a system that supports WSL 2, this option should be turned on by default.
From the Resources tab, under the WSL Integration section, ensure that Enable integration with my default WSL distro is selected and that it is also enabled for any additional distros.
Select Apply and Restart to restart Docker. This may also involve a full computer restart.
In Docker Desktop, go to Settings (the cog wheel in top right corner) / General and ensure that SBOM indexing and enable background SBOM indexing are both turned OFF. You may need to scroll down to find those settings. Also, ensure that under Settings / Features in Development all Beta and Experimental features are turned OFF. These settings can otherwise adversely impact performance on computers with constrained capacity.

Git installation

Git versions

Git is the most commonly used version control system for source code. It is very useful in the context of G-Cubed models for management of model data files, model definitions, simulation experiments, and experiment programs. It is also useful for managing devcontainer definitions.

For this configuration Git must be installed in both the Windows and Linux environments. If required, detailed instructions for installing Git on Linux distributions running on WSL 2 are set out here.

Git installation steps

Check that git is installed (and updated to the latest version) on Linux:

Open a Windows Command Prompt.
Start Linux by running:
```
 wsl
```
Run the git installation command (shown below for the Ubuntu Linux distribution):
```
 sudo apt-get install git
```
If Git is installed, that will be indicated. If appropriate, Git will be updated when this command has been run.
Install the Windows version of Git

You also need to install Git for Windows. This can be useful if you want to use Git repositories from Windows directly without working from within Linux. Git for Windows is also required so that you can make use of the Git Credential Manager described below (mandatory for this configuration). The Git Credential Manager is a part of the Windows version of Git rather than the Linux version of Git.

It is important to note that the Windows version of Git is not appropriate to use with devcontainers. Do not clone devcontainer repositories from GitHub to the Windows file system using the Windows version of Git.
Configure Git to use the Git Credential Manager supplied with Git for Windows, and to respect repository end-of-line settings.

The Git Credential Manager is a secure Git credential helper for Git that can be used from Linux running under WSL 2. It enables multi-factor authentication support for GitHub repositories. It integrates into the GitHub authentication flow and, once you’re authenticated to GitHub, requests a new authentication token. It stores the token in the Windows Credential Manager. After the authentication, you can use Git to talk to GitHub without reauthenticating.

Assuming that the Windows Git version is 2.39.0 or later, run the following command after starting Linux using the wsl command:
```
 git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
```
You can check the version of the Windows Git installation by opening a Windows Command Prompt and running:
```
 git --version
```
The instructions here explain how to configure the Git Credential Manager supplied with the Windows version of Git, for earlier versions of Git.

Configure Git. This needs to be done for both the Windows and Linux versions of Git. Open a new Windows Command Prompt and type (replacing Your Name and youremail@domain.com as necessary):

 git config --global core.autocrlf input

 git config --global user.name "Your Name"

 git config --global user.email "youremail@domain.com"

Then start wsl and run the same commands:

wsl

 git config --global core.autocrlf input

 git config --global user.name "Your Name"

 git config --global user.email "youremail@domain.com"

Run the following command in each of the Windows and WSL contexts to check if you have been successful:
```
 git config --global -l
```
You should see entries for user.name, user.email, core.autocrlf and credential.helper reflecting your new setup.

VS Code for Windows installation and configuration

You need to install the Windows version of VS Code. VS Code will then automatically install VS Code server in WSL, allowing you to use the Windows version of VS Code in both the Windows and Linux contexts.

VS Code is available from the Visual Studio website.

VS Code installation steps

Download the VS Code User installer for Windows from the VS Code download page.
Run the VS Code User Setup executable to perform the installation. This provides the basic VS Code installation.
Once VS Code for Windows is installed, restart your machine.
Once your computer has restarted, try starting VS Code by opening a Windows Command Prompt in any folder and running the command:
```
 code
```
The VS Code text editor should open.

VS Code extensions

The capabilities of VS Code can be augmented using VS Code extensions.

Once VS Code is running successfully, you need to install the VS Code Dev Containers extension by clicking here and then clicking the Install the Dev Containers extension button. Once complete, review the instructions here to test the installation.

If this is successful then congratulations! Your installation has been successful. You are now ready to run G-Cubed using devcontainers on your Windows computer. Make sure that you do it the right way, as explained below! Things can go wrong if you try to work within Windows rather than Linux.

Running devcontainers on Windows

Open a Windows Command Prompt to get access to a windows prompt that can be used to start WSL 2.
Start a WSL terminal session by typing wsl and hitting ENTER
Change to your Linux GitHub folder that you created earlier (if not already there) with the command:
```
 cd ~/github
```
Clone a devcontainer repository to the local drive. For instance, working with the 2R version of G-Cubed:
```
 git clone https://github.com/<YOUR GITHUB ACCOUNT>/gcubed-2R.git
```
You will need to clone the fork of the https://github.com/McKibbin-Software-Group/gcubed-2R repository that you created, as explained in the instructions for using G-Cubed in the Cloud, rather than the gcubed-2R repository itself.

Doing so allows you to push your changes back to your GitHub repository in order to protect you from losing any of your work. Failure to clone your own fork of the main repository exposes you to significant risk of losing all your work.

HINT: an easy way to get the URL of your repository that you want to clone is to navigate to your fork’s page in GitHub, click the green <> Code button, select the Local tab, select HTTPS under Clone, and then copy the provided https URL to clipboard.

If you encounter authentication issues while cloning the repository, make sure that you have configured the Git Credential Manager supplied with Git for Windows, as described above.
Change to the repository folder. For example, if you have cloned the gcubed-2R devcontainer repository the Git clone command will create a gcubed-2R folder so run:
```
 cd gcubed-2R
```
Start VS Code from that root folder of the devcontainer repository.
```
 code .
```
Note that the the . ‘dot’ or ‘full stop’ after code is necessary because it instructs VS Code to open the current folder.

VS Code should open and display all the files and directories in the the root folder of the devcontainer repository. These have been copied to the Linux file system by the Git clone command.

The devcontainer has not started yet. You are still in Linux, which means you can just edit the files in the devcontainer repository, but none of the development environment is running and you can’t access the G-Cubed software.
Reopen the folder in VS Code as a devcontainer

After starting, VS Code typically shows a small dialog in the lower right corner offering to reopen as a devcontainer. Use that dialog to confirm that you do want to reopen the VS Code folder as a devcontainer.

If you don’t use the dialog to reopen as a devcontainer then you will need to manually reopen the folder as a devcontainer. You can do this by pressing CTRL+SHIFT+P and typing reopen. This will show a search window in the centre top of the VS Code window with the option Dev Containers: Reopen in Container at or near the top of the list of search results. Select that option.
Make a cup of tea

The devcontainer can take a few minutes to open the first time it is used. This is because it requires a lot of software as well as the G-Cubed model files to be downloaded and installed.

Once the installation is complete you will have access to the G-Cubed model and the software required to use it, all from within the devcontainer that has been opened in VS Code.

To close the devcontainer, simply close VS Code.

When you next restart VS Code in the root folder of the devcontainer repository, you will again be prompted to reopen as devcontainer. Do so and you will be able to restart your work from where you left off.

By default, VS Code remembers where you left off and will restart in the same location. Simply starting VS Code from within Windows should automatically restart the devcontainer and open the previous editor windows.

Using the Windows file explorer from within Linux

To make it easy to use the Windows File Explorer from within Linux, it helps to perform a little customisation for your Linux user account:

Open a Windows Command Prompt.
Start Linux by running the wsl command.
Edit the bash shell alias definitions by entering the command:
```
 code ~/.bash_aliases
```
and add the following alias definition:
```
 alias start='/mnt/c/windows/explorer.exe'
```
Log out of Linux by running the command:
```
 exit
```
That command will return you to the Windows Command Prompt. When you next start Linux, the alias will be active and you can open Windows Explorer from within Linux by running:
```
 start .
```
Note the . dot again here. This will open Windows File Explorer to give access to the files in the current folder of the Linux file system.