Docker Container Windows

Docker Container Setup (Windows 10/11 + WSL2 Ubuntu 24.04)

This page documents the complete, validated setup for running our ROS2 Jazzy devcontainer on Windows 10/11 using Ubuntu 24.04 on WSL2, with working USB serial passthrough and GUI applications.

---

Prerequisites

Windows requirements

• Windows 10/11 (admin access recommended)
• Internet connection
• Ubuntu 24.04 installed as a WSL2 distro

Install these tools on Windows

• Visual Studio Code (VS Code)
• VS Code extensions:
  • Remote - WSL
  • Dev Containers
• usbipd-win (USB passthrough to WSL)
• VcXsrv (X server for GUI apps)

---

1) Install WSL Ubuntu 24.04

Open PowerShell (Admin) and enable WSL:

wsl --install --no-distribution

Then install Ubuntu 24.04 specifically:

wsl --install -d Ubuntu-24.04

Verify WSL2 and distro presence:

C:\Users\admin>wsl -l -v
  NAME              STATE           VERSION
* Ubuntu-24.04      Running         2

In case the version is 1, switch to 2 by:

wsl --set-version Ubuntu-24.04 2

What these commands do

• wsl --install --no-distribution: enables the WSL feature and required components without installing a default distro.
• wsl --install -d Ubuntu-24.04: installs Ubuntu 24.04 LTS specifically, so you don't end up with whatever the current Microsoft-Store default happens to be.
• wsl -l -v: lists installed WSL distros and shows their WSL version (1 or 2).

---

2) Install Docker Engine inside Ubuntu (WSL)

When entering Ubuntu WSL, you are entering another system/server. Your terminal will reflect this. To go back to the Windows Terminal, type exit.

Enter Ubuntu WSL:

wsl -d Ubuntu-24.04

Inside Ubuntu, install Docker Engine and add your user to the docker group:

sudo apt-get update
sudo apt-get install -y docker.io
sudo usermod -aG docker $USER

Restart WSL (from Windows Terminal) so group membership applies:

wsl --shutdown
wsl -d Ubuntu-24.04

Start Docker:

• If systemd is enabled in your WSL:

sudo systemctl enable --now docker

• If systemd is not enabled (common): run dockerd in one Ubuntu terminal and leave it running:

sudo dockerd

Verify Docker is Ubuntu-hosted (NOT Docker Desktop):

docker info | grep -E "Operating System|Name|Server Version"

Expected: Operating System shows Ubuntu 24.04.x LTS and Name is your machine/WSL hostname. If it says Docker Desktop, see Troubleshooting.

What these commands do

• apt-get update: refreshes Ubuntu's package index.
• apt-get install -y docker.io: installs Docker Engine packages from Ubuntu repositories.
• wsl --shutdown: fully stops WSL so changes (like group membership) take effect.
• dockerd: starts the Docker daemon (the background service Docker needs).
• docker info: prints Docker daemon info so you can confirm where it is running.

---

3) Install VS Code + Dev Containers

Install VS Code on Windows, then install these extensions:

• Remote - WSL (Microsoft)
• Dev Containers (Microsoft) Open VS Code once to ensure extensions activate properly.

---

4) Clone the repo (IMPORTANT path note)

Avoid cloning under the Windows filesystem and instead clone inside the WSL filesystem.

Ensure you are in WSL, then run:

mkdir -p ~/repos
cd ~/repos
git clone <REPO_URL>
cd uvic-rover-2027

What these commands do

• mkdir -p ~/repos: creates a folder for repositories (no error if it already exists).
• git clone <REPO_URL>: downloads the repository.
• cd ...: changes into the repo directory.

---

5) Open the repo in WSL and start the devcontainer

From Ubuntu WSL inside the repo folder, open VS Code:

code .

Confirm VS Code shows WSL: Ubuntu-24.04 (bottom-left). Then open the Command Palette and run:

• Dev Containers: Rebuild and Reopen in Container

Success indicator: bottom-left shows Dev Container: ....

If there are ANY errors, common indicators could be the Dockerfile or .devcontainer file. Make sure to read the errors outputted carefully.

What this does

• code .: opens the current folder in VS Code (connected to WSL).
• Rebuild/Reopen: builds the container image and connects VS Code into it.

---

6) Configure VcZsrv for GUI applications

GUI tools like RViz and rqt require a running X server on Windows. The container reads your display address from a local .env file that is gitignored.

The WSL2 default gateway IP (used to reach the Windows host) can change after every Windows reboot, so rather than setting it manually once, your WSL2 ~/.bashrc automatically writes the correct IP to the .env file every time a WSL2 terminal opens. By the time you open VS Code and start the container, the .env file is already up to date.

Set up Automatic DISPLAY

This is a one-time setup in WSL2 that keeps your .env file up to date automatically on every WSL2 startup.

Open your WSL2 ~/.bashrc (this is outside the container, in WSL2 itself):

nano ~/.bashrc

Add this block at the bottom, updating the path to match where you cloned the repo:

# Auto-update DISPLAY for ROS2 dev container
WIN_IP=$(ip route show default | awk '/default/ {print $3; exit}')
echo "DISPLAY=${WIN_IP}:0.0" > ~/repos/uvic-rover-2027/.devcontainer/.env

Save and exit, then apply it immediately:

source ~/.bashrc

What this does:

• Every time you open a WSL2 terminal, it reads the current Windows host IP from the network route
• It writes that IP into .devcontainer/.env in your repo
• The container picks it up on the next start or rebuild — you never need to update it manually

Verify the .env file is correct

After sourcing your .bashrc, check it was written correctly:

cat .devcontainer/.env

Expected output (your IP may differ):

DISPLAY=172.26.144.1:0.0

First-time VcXsrv setup

1. Open XLaunch on Windows
2. Choose the "Multiple Windows" display mode
3. Display number should be set to 0
4. Select Start no Client
5. Check Disable Access Control AND do NOT check Native opengl
6. Click Finish

REBUILD THE CONTAINER!

To verify GUI forwarding

Inside the container terminal, run:

xeyes

A small windows with a pair of eyes following your cursor should appear. If you get an error Authorization required or Can't open display: Ensure that VcXsrv is running correctly with the steps listed above.

---