Windows Setup (WSL2)

MooseStack runs on Windows through the Windows Subsystem for Linux (WSL2). This guide walks you through setting up a complete development environment.

Prerequisites

Before you begin, ensure your system meets these requirements:

• Windows 10 or 11: Windows 10 version 2004 (build 19041) or later, or Windows 11. See Microsoft's WSL prerequisites.
• Hardware virtualization: VT-x/AMD-V enabled in BIOS, and at least 4 GB RAM (Docker). See Microsoft's WSL containers guide.
• Internet access: Required to download Ubuntu and packages.
• Docker Desktop: Used to run MooseStack's local containers.
• (Optional) Windows Terminal: Recommended for a better terminal experience. See Microsoft's guidance.

Step 1: Enable WSL 2 and Install Ubuntu

1. Open PowerShell as Administrator (right-click Start menu, choose PowerShell (Admin)).

2. Run:

   Terminal

   Copy code

   wsl --install

3. If prompted, restart your computer to complete the installation.

4. If wsl --install only shows help text:

   1. List available distros:

      Terminal

      Copy code

      wsl --list --online

   2. Install Ubuntu explicitly:

      Terminal

      Copy code

      wsl --install -d Ubuntu

5. Complete Ubuntu's first-time setup. After reboot, Windows should automatically launch Ubuntu. If it doesn't open, launch Ubuntu from the Start menu.

6. Create your Linux user. You'll be prompted to create a UNIX username and password for Ubuntu (separate from your Windows credentials). You won't see characters as you type the password—this is normal.

7. Verify you're on WSL2. In PowerShell (not the Ubuntu shell), run:

   Terminal

   Copy code

   wsl -l -v

   If your Ubuntu distro shows version 1, upgrade it:

   Terminal

   Copy code

   wsl --set-version Ubuntu 2

Step 2: Update Linux Packages

Now that Ubuntu is running in WSL, update its package lists and upgrade installed packages:

1. In the Ubuntu terminal, run:

   Terminal

   Copy code

   sudo apt update && sudo apt upgrade -y

2. (Optional) Install basic tools:

   Terminal

   Copy code

   sudo apt install -y build-essential curl git

Step 3: Install and Configure Docker

MooseStack uses Docker containers under the hood for components like ClickHouse and Redpanda. On Windows, the recommended way to run Docker with WSL2 is via Docker Desktop.

Install Docker Desktop

1. Download Docker Desktop for Windows from Docker and run the installer. During installation, it may prompt to enable WSL2 features if not already enabled.
2. Launch Docker Desktop. In the taskbar, you'll see the Docker whale icon (it may take a few seconds to start up the first time).

Configure Docker Desktop with WSL2

1. Enable WSL2 backend: In Docker Desktop, open Settings. Under General, ensure "Use the WSL 2-based engine" is checked.
2. Integrate with Ubuntu: In Resources > WSL Integration, enable integration for Ubuntu (or the distro you installed).
3. Allocate sufficient resources: MooseStack needs at least 2.5 GB of Docker memory. In Resources, set memory to 3–4 GB to be safe.
4. Apply settings: Click Apply & Restart if you changed any settings.

Test Docker inside WSL

In the Ubuntu terminal, run:

docker --version
docker run hello-world

The hello-world container should print a "Hello from Docker!" message and exit. You can also run docker ps to confirm the Docker daemon is reachable from WSL (it should show no containers running).

Step 4: Install Node.js inside WSL2

You need to install Node.js inside the WSL2 Ubuntu environment—not the Windows version of Node.js. The recommended approach is to use nvm (Node Version Manager), which makes it easy to install and switch between Node.js versions.

1. In your Ubuntu terminal, install nvm (see nvm releases for the latest version):

   Terminal

   Copy code

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

   Latest nvm version

   Check the nvm releases page for the most current version tag and update the URL accordingly.

2. Close and reopen your terminal (or run source ~/.bashrc) to load nvm.

3. Install Node.js 22 (LTS):

   Terminal

   Copy code

   nvm install 22

4. Verify the installation:

   Terminal

   Copy code

   node --version

   You should see a version like v22.x.x.

Step 5: Install MooseStack

You now have a working Ubuntu instance on your Windows machine with Docker and Node.js installed. Continue with the MooseStack installation—just make sure to run all commands in the Ubuntu terminal, not PowerShell or Command Prompt.

Tips for Windows Development

• Use VS Code with WSL: Install the WSL extension for VS Code to edit files directly in your WSL environment.
• File system performance: Keep your MooseStack projects in the Linux filesystem (/home/youruser/) rather than /mnt/c/ for better performance.
• Windows Terminal: Use Windows Terminal for a modern terminal experience with tabs and better WSL integration.