Skip to content

WSL (Windows Subsystem for Linux)

Overview

The dev_tool can be built and run inside WSL2 on Ubuntu. This guide walks through the setup process for building and running the dev_tool from a WSL environment, using the project files on the Windows filesystem.

Prerequisites

  • Windows 11 with WSL2 enabled
  • Ubuntu installed via WSL
  • Docker Desktop for Windows with WSL integration enabled
  • A dev-tool key (Dev Tools Key) from the BitWarden vault
  • pyproject.toml in the root directory of your project
  • development.env in the root directory of your project

Docker Desktop Configuration

Docker Desktop must be configured to expose the Docker daemon to your WSL distro:

  1. Open Docker Desktop on Windows
  2. Navigate to Settings > Resources > WSL Integration
  3. Toggle on your Ubuntu distro
  4. Click Apply & restart
  5. Verify from WSL:
docker version

System Dependencies

Open your WSL terminal and install the required system packages:

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libffi-dev liblzma-dev libpq-dev

uv

The build.sh script will install uv automatically on the first run. If you need to install it manually:

curl -sSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

If uv is installed but not found in subsequent sessions, add the source line to your shell profile:

echo 'source $HOME/.local/bin/env' >> ~/.bashrc
source ~/.bashrc

Personal Access Token (PAT)

The dev_tool requires a GitHub PAT to check for updates. Copy the token from your Windows setup:

mkdir -p ~/stratus
cp /mnt/c/Users/<Username>/stratus/dev_tool_github_pat ~/stratus/

Replace <Username> with your Windows username.

Building the dev_tool

The build.sh script is located inside the dev_tool directory of the repository. It can be run from any directory.

Since the script lives on the Windows filesystem, line endings must be fixed before the first run and after any edit from Windows:

sed -i 's/\r$//' /mnt/c/Users/<Username>/PycharmProjects/dev-tools/dev_tool/build.sh
chmod +x /mnt/c/Users/<Username>/PycharmProjects/dev-tools/dev_tool/build.sh

Build both the launcher and CLI:

/mnt/c/Users/<Username>/PycharmProjects/dev-tools/dev_tool/build.sh

You can also build them individually:

/mnt/c/Users/<Username>/PycharmProjects/dev-tools/dev_tool/build.sh dev_tool
/mnt/c/Users/<Username>/PycharmProjects/dev-tools/dev_tool/build.sh cli

The executables are placed in ~/stratus/.

Note:

The build.sh script does not run git pull. Pull the latest code from Windows before building.

Running the dev_tool

Navigate to your project directory and run the launcher:

cd /mnt/c/Users/<Username>/PycharmProjects/<project>
~/stratus/dev_tool

Running the Django Server

When running the Django development server from WSL, use the Run on local IP option from the dev_tool menu. The server will bind to 0.0.0.0:8000, which allows Windows to access it.

Access the server from your Windows browser at:

http://localhost:8000/

Note:

WSL2 runs in a virtual machine with its own network adapter. Binding to 0.0.0.0 is required for Windows to reach the server through localhost forwarding. The 127.0.0.1 address is local to the WSL VM and is not accessible from Windows.

Stale Lock Port

If the dev_tool exits unexpectedly (e.g., via a forced kill or WSL crash), the lock socket may persist and prevent relaunch. You will see a message like:

Another instance is running on 127.0.0.1:37122.

If no instance is actually running, restart WSL from PowerShell on Windows:

wsl --shutdown

Then reopen WSL and run the dev_tool again.

Virtual Environments

Virtual environments created in WSL are not compatible with Windows and vice versa. If you rebuild a development environment in WSL, the .venv directory will be created with Linux binaries. This will cause issues when returning to Windows.

Before switching back to Windows, remove the .venv directory created by WSL and rebuild the development environment from Windows using the dev_tool.