# WSL Environment Setup
## Purpose
Typically, when **developing an AI accelerator**, we do not train the model weights from scratch; instead, **we leverage pre-trained parameters from established frameworks**. Our primary objective is to execute model inference to perform a **hardware-software co-validation**. Therefore, the software implementation must still be executed on high-performance GPUs. There are several ways to achieve the goal:
* **Dedicated Linux Server** (Lab-provided or Self-built):
While high-performing, this **requires managing a separate machine** or transitioning entirely to a Linux-based OS. As a Windows user, I find a complete OS switch disruptive to my established productivity workflow.
* **Hyper-V with GPU-PV** (GPU Partitioning):
This method allows resource sharing but is highly restrictive regarding hardware compatibility. **Consumer-grade laptop GPUs** (like the RTX 3060) typically **do not support this enterprise-level feature**.
* **Hyper-V with DDA** (Discrete Device Assignment):
DDA offers direct hardware access but follows a "winner-takes-all" model. Once the GPU is assigned to the VM, **the host Windows system loses its display and compute capabilities**, making multitasking impossible.
* **WSL2** (Windows Subsystem for Linux) **with GPU Sharing**:
WSL2 strikes the best balance. Although it introduces a marginal performance overhead compared to native Linux, it provides a seamless, shared-resource environment. It allows me to leverage powerful **Linux tools and Docker while retaining** the convenience of the **Windows ecosystem**.

Given my hardware configuration—a laptop equipped with an **Intel i7-11800H CPU**, **Intel UHD Graphics**, and an **NVIDIA RTX 3060 GPU**—utilizing WSL2 is the most effective option for my development workflow.

## Steps
1. Upgrade to Windows 11 Pro to enable Hyper-V support.
2. Install WSL2 and set up an Ubuntu distribution.
3. Configure Docker Engine within the WSL2 environment.
4. Install NVIDIA Container Toolkit.
5. Integrate VS Code with Ubuntu, WSL, and Docker for a seamless development workflow.

## Windows 11 Pro
My version is originally Windows 11 Home. To upgrade it, there are several ways. Here, I buy the **digital license** from the Microsoft store, which cost NT$ 3000. You can come to the settings below first. If you want to buy upgrade license, you can tap on the activation state and there will be an option linked to MS store.
Unlike other activation methods, a Digital License is linked directly to your Microsoft account. This allows you to seamlessly transfer the upgrade to a new PC whenever you switch devices.

## Hyper-V, WSL2, Ubuntu
### Enable Hyper-V
First, ensure that you are running **Windows 11 Pro** or **Windows 11 Enterprise**, as these versions are required to access advanced virtualization features like Hyper-V.
Navigate to Optional features under the System settings, then click on **More Windows features**. From there, you will find the option to enable Hyper-V. After restarting the computer, Hyper-V will be fully enabled and ready for use.

### Install WSL2 and Ubuntu
You can reference to this video:
https://youtu.be/PaEcQmgEz78?si=JIhHLIKHaS3aU1P8
1. To install WSL2, you will need to install the following two functions first. These two are **Virtual Machine Platform** and **Windows Subsystem for Linux**.
2. Open the Command Prompt and run it as administrator.
3. Type the following cmd, then it will automatically install wsl2 and ubuntu for you.

    wsl --install

4. Type the following cmd, and you will find all the Linux Distribution (Distro).

    wsl -list -v


5. Because the Linux system is built on C drive, we want it to run at our D dive. We can run these cmds:

    # you will find ubuntu.tar in your desktop.
    wsl --export Ubuntu ubuntu.tar

    # Create a folder in the D drive. Here, I named it as wsl2.
    # Ubuntu2 will be your system name. You can change it.
    wsl --import Ubuntu2 D:\wsl2 C:\Users\User\Desktop\ubuntu.tar

    # Set default Linux system to Ubuntu2
    wsl --set-default Ubuntu2

    # Remove the origin system named Ubuntu on the C drive 
    wsl --unregister Ubuntu

6. By clicking the Ubuntu2 figure, you will get into the linux system.
7. If you encounter this problem:

    Error code:
    Wsl/Service/CreateInstance/ReadDistroConfig/WSL_E_DISTRO_NOT_FOUND

It is because it connected to the previous system named Ubuntu. You can solve this by clicking the setting button here.
Go to the profile of "Ubuntu" and change the Command line to:

    wsl.exe -d Ubuntu2

The command-line profile should then automatically update its name to "Ubuntu2".

8. Quickly check basic functions

    # You should see the result /home/USER_NAME
    pwd

    # It is used to check the disk space usage across all mounted file systems in a Linux environment.
    df -h

    # You can access to the datas in your drive. For example: I want to see the D drive.
    cd /mnt/d

    # By using the cmd below you can get back to home (or cd ~).
    cd

    # Check if wsl2 can detect your GPU
    nvidia-smi

If you close the Ubuntu2 terminal, the distribution may enter suspended mode to conserve system resources. You can shutdown the system by doing so:

    wsl --shutdown

## Install docker
You can reference to this blog:
https://blog.miniasp.com/post/2025/06/14/How-to-remove-Docker-Desktop-and-install-Docker-Engine-on-Windows-with-WSL-2
1. Install docker engine on wsl2 (instead of installing docker desktop):

    # 1. Download the Docker installation script
    # Reference: https://docs.docker.com/engine/install/ubuntu/#install-using-the-convenience-script
    curl -fsSL https://get.docker.com -o get-docker.sh

    # 2. Execute the installation script
    # Note: The script may prompt you to install Docker Desktop. You may ignore it. 
    sudo sh get-docker.sh

    # 3. Manage Docker as a non-root user by adding your account to the docker group
    # Reference: https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user
    sudo usermod -aG docker $USER
    # Note that you need to shutdown wsl2 to update this information.
    
    # 4. Verify your identity 
    id $USER

    # 5. Verify the installation and check versions
    docker --version
    docker compose version

2. Use **systemd** to control docker engine.
Normally, systemd is enabled automatically. You should check it as follow:

    # You may use vim to edit the file.  Here, I used another method.
    # It is more user friendly.
    sudo nano /etc/wsl.conf
    
    # we need to check if it shows "[boot] systemd=true".

**Note: The `^` means crtl.**

    # You can verify if the Docker service is properly registered using the following command:
    systemctl list-unit-files --type=service | grep docker
    # Note that you may use "q" to exit from the cmd above.

    # To check the real-time operational status of the Docker service, use:
    systemctl status docker.service

## Install NVIDIA Container Toolkit
Though we can access to our GPU on wsl2. We may not detect the GPU when using the docker on wsl2. So, we need to install the NVIDIA Container Toolkit.
You can reference this github: https://gist.github.com/atinfinity/f9568aa9564371f573138712070f5bad
1. Install toolkit:

    curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list && sudo apt-get update
    sudo apt-get install -y nvidia-container-toolkit

2. Restart docker service to update:

    sudo systemctl restart docker

3. Run a sample to check if the toolkit works on docker:

    docker run -it --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

## Connect wsl2 to VScode
You may reference to MS website and the video:
https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode
https://youtu.be/R88B_ldc6O8?si=vu3zw-NDmVEjw89a
1. Install extension pack on VScode:
2. Open ubuntu to install extension pack locally:

    # Install essential networking and security tools
    sudo apt-get install wget ca-certificates

    # These tools ensure that:
    # 1. 'wget' can download files from the internet via command line.
    # 2. 'ca-certificates' allows the system to verify SSL/TLS connections (HTTPS).

    # Open up VScode on ubuntu
    # It may take a while for the first time. 
    # The video install VScode server very fast. My situation is much more slower. It takes about 30 min?
    code .

And install "Docker".

## Reference
* https://youtu.be/PaEcQmgEz78?si=JIhHLIKHaS3aU1P8
* https://blog.miniasp.com/post/2025/06/14/How-to-remove-Docker-Desktop-and-install-Docker-Engine-on-Windows-with-WSL-2
* https://gist.github.com/atinfinity/f9568aa9564371f573138712070f5bad
* https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode
* https://youtu.be/R88B_ldc6O8?si=vu3zw-NDmVEjw89a