Ubuntu Installation

This guide covers installing Ubuntu from the Microsoft Store and configuring it for optimal development performance.

1. Install Ubuntu from Microsoft Store

1.1. Option 1: Microsoft Store (recommended)

  1. Open the Microsoft Store

  2. Search for "Ubuntu 24.04 LTS"

  3. Click Get or Install

  4. Wait for the download to complete

  5. Click Open to launch Ubuntu for the first time

1.2. Option 2: Command line installation

Open PowerShell and run:

wsl --install -d Ubuntu-24.04

2. First boot configuration

When Ubuntu launches for the first time:

  1. Wait for the installation to complete (this may take a few minutes)

  2. Enter a username when prompted (lowercase, no spaces)

  3. Enter and confirm a password

    This password is for sudo operations within Ubuntu. It does not need to match your Windows password.

3. Update system packages

After initial setup, update all packages:

sudo apt update && sudo apt upgrade -y

This ensures you have the latest security patches and software versions.

4. Configure .wslconfig

The .wslconfig file controls WSL2 resource allocation. Create or edit this file on the Windows side.

4.1. Create the configuration file

  1. Open File Explorer

  2. Navigate to C:\Users\<YourUsername>\

  3. Create a new file named .wslconfig (note the leading dot)

4.2. Recommended settings

Add the following content to .wslconfig:

[wsl2]
memory=8GB
processors=4
swap=4GB
localhostForwarding=true

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true
Setting Description

memory

Maximum memory allocated to WSL2. Adjust based on your system RAM (8GB recommended for 16GB+ systems).

processors

Number of CPU cores allocated to WSL2. Set to half your total cores for a good balance.

swap

Swap space size. Helps prevent out-of-memory issues during large builds.

localhostForwarding

Allows accessing WSL2 services from Windows via localhost.

autoMemoryReclaim

Gradually returns unused memory to Windows, preventing WSL2 from consuming excessive RAM.

sparseVhd

Automatically compacts the virtual disk, reducing storage usage.

4.3. Apply the configuration

Restart WSL2 to apply the changes:

wsl --shutdown

Then reopen Ubuntu from the Start menu or run:

wsl

5. Configure Windows Defender exclusions

Windows Defender real-time scanning can significantly slow down WSL2 filesystem operations. Add exclusions for WSL2 directories.

Open PowerShell as Administrator and run:

# Exclude WSL2 virtual filesystem
Add-MpPreference -ExclusionPath "\\wsl$\"

# Exclude WSL2 distribution files
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited*"

# Exclude WSL2 processes
Add-MpPreference -ExclusionProcess "vmmem"
Add-MpPreference -ExclusionProcess "wsl.exe"
Add-MpPreference -ExclusionProcess "wslhost.exe"

These exclusions reduce security scanning for WSL2 files. Ensure you only download and run trusted code within WSL2.

6. Create development directory structure

Create the recommended directory structure for development:

mkdir -p ~/dev/ems

This creates:

  • ~/dev/ - Root development directory

  • ~/dev/ems/ - Event Management System projects

Always place your projects in the native WSL2 filesystem (~/dev/) rather than on Windows mounts (/mnt/c/). This is critical for performance.

7. Verify installation

Check that Ubuntu is running as WSL version 2:

wsl --list --verbose

You should see output similar to:

  NAME            STATE           VERSION
* Ubuntu-24.04    Running         2

If VERSION shows 1, convert to WSL2:

wsl --set-version Ubuntu-24.04 2

8. Accessing files between Windows and WSL2

8.1. From Windows to WSL2

Access WSL2 files in File Explorer:

  • Open File Explorer

  • Navigate to \\wsl$\Ubuntu\home\<username>\

  • Or type \\wsl$\ in the address bar to see all distributions

8.2. From WSL2 to Windows

Access Windows drives from within Ubuntu:

# Windows C: drive
ls /mnt/c/

# User Documents folder
ls /mnt/c/Users/<WindowsUsername>/Documents/

Accessing /mnt/c/ from WSL2 is significantly slower than the native filesystem. Use this only for occasional file access, not for active development.

9. Next steps

Proceed to Development Tools to install OpenJDK, Maven, Git, and other essential development tools.