Skip to content

wsl2-setup.md

Latest commit

 

History

History
254 lines (173 loc) · 5.57 KB

wsl2-setup.md

File metadata and controls

254 lines (173 loc) · 5.57 KB

WSL2 Setup Guide (Windows)

CommandMate runs on Windows via WSL2 (Windows Subsystem for Linux). Since CommandMate depends on tmux, WSL2 is required — native Windows is not supported.

Prerequisites

  • Windows 10 (version 2004+) or Windows 11
  • WSL2 enabled with Ubuntu 22.04 or later
  • Windows Terminal (recommended)

1. WSL2 Setup

If WSL2 is not yet installed, open PowerShell as Administrator and run:

wsl --install -d Ubuntu

Restart your PC when prompted, then launch Ubuntu from the Start menu to complete the initial setup (username/password).

Verify WSL2 is active:

wsl --list --verbose

The VERSION column should show 2.

2. Install Dependencies

Open your WSL2 terminal (Ubuntu) and run:

# Update packages
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y git tmux build-essential

Install GitHub CLI (gh)

CommandMate's Issue連携機能に必要です:

# GitHub公式リポジトリを追加してインストール
(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

# 確認
gh --version

# GitHubにログイン
gh auth login

Install Node.js (v20+)

Note: Ubuntu's default apt repository ships an outdated Node.js. If you already have an old version installed via apt, remove it first:

sudo apt remove -y nodejs npm
sudo apt autoremove -y
sudo rm -rf /usr/local/lib/node_modules
sudo rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx

We recommend using nvm for Node.js version management:

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

# Reload shell
source ~/.bashrc

# Install latest LTS
nvm install --lts
nvm use --lts

# Verify (v22.x.x or later)
node -v
npm -v

3. Clone & Build

# Clone the repository
git clone https://github.com/Kewton/CommandMate.git
cd CommandMate

# Install dependencies
npm install

# Build
npm run build:all

4. Initialize & Start

# Initialize (interactive setup)
npx commandmate init

# Start the server
npx commandmate start --daemon

The server starts at http://localhost:3000 by default.

5. Access from Windows Browser

localhost access (default)

In most WSL2 configurations, localhost is automatically forwarded to WSL2. Open your Windows browser and navigate to:

http://localhost:3000

If localhost does not work

If localhost forwarding is not working, find the WSL2 IP address:

# Run inside WSL2
hostname -I

Then access http://<WSL2_IP>:3000 from your Windows browser.

To bind CommandMate to all interfaces (required if using the WSL2 IP):

CM_BIND=0.0.0.0 npx commandmate start --daemon

6. Development Mode

For development with hot-reload:

cd CommandMate

# Start dev server
npm run dev

Open http://localhost:3000 in your Windows browser.

Troubleshooting

tmux not found

sudo apt install -y tmux
tmux -V

Node.js version too old

# apt版が入っている場合は先に削除
sudo apt remove -y nodejs npm && sudo apt autoremove -y

# nvmで最新LTSをインストール
nvm install --lts
nvm use --lts
node -v

better-sqlite3: NODE_MODULE_VERSION mismatch

npm install 時と実行時でNode.jsのバージョンが異なると、以下のエラーが発生します:

was compiled against a different Node.js version using
NODE_MODULE_VERSION 137. This version of Node.js requires
NODE_MODULE_VERSION 115.

原因: nvm でNode.jsバージョンを切り替えた後、ネイティブモジュールが古いバージョン向けのまま残っている。

解決方法:

# 現在のNodeバージョンを確認
node -v

# ネイティブモジュールを現在のバージョン向けにリビルド
npm rebuild better-sqlite3

# 再起動
npx commandmate start

Tip: nvm でバージョンを切り替えたら、必ず npm rebuild better-sqlite3 を実行してください。 それでも解決しない場合は rm -rf node_modules && npm install で再インストールしてください。

Port already in use

# Check what is using the port
ss -tlnp | grep :3000

# Stop the existing server
npx commandmate stop

Cannot access from Windows browser

  1. Check the server is running: npx commandmate status
  2. Try the WSL2 IP address: hostname -I
  3. Start with CM_BIND=0.0.0.0 to bind to all interfaces
  4. Check Windows Firewall is not blocking the port

File permission issues

WSL2 mounts Windows drives under /mnt/c/, /mnt/d/, etc. For best performance and compatibility, keep the repository inside the WSL2 filesystem (e.g., ~/CommandMate), not on a Windows-mounted path.

# Good - WSL2 native filesystem
cd ~
git clone https://github.com/Kewton/CommandMate.git

# Avoid - Windows mounted path (slower, permission issues)
# cd /mnt/c/Users/YourName/CommandMate