Windows Development Setup

Complete guide to setting up your Windows development environment for Chatwoot contribution using WSL2.

Windows Development Setup

This guide will walk you through setting up your Windows development environment for contributing to Chatwoot. We’ll use Windows Subsystem for Linux 2 (WSL2) which provides the best development experience on Windows.

Requirements

You need to install the Windows Subsystem for Linux 2 (WSL2) on your Windows machine.

Prerequisites

• Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11
• Administrator privileges on your Windows machine

Step 1: Enable Developer Mode

The first step is to enable “Developer mode” in Windows. You can do this by opening up Settings and navigating to “Update & Security”. In there, choose the tab on the left that reads “For Developers”. Turn the “Developer mode” toggle on to enable it.

Step 2: Enable Windows Subsystem for Linux

Next you have to enable the Windows Subsystem for Linux. Open the “Control Panel” and go to “Programs and Features”. Click on the link on the left “Turn Windows features on or off”. Look for the “Windows Subsystem for Linux” option and select the checkbox next to it.

You’ll also need to enable “Virtual Machine Platform” for WSL2. Make sure both checkboxes are selected:

• ✅ Windows Subsystem for Linux
• ✅ Virtual Machine Platform

After enabling these features, restart your computer.

Step 3: Install WSL2 and Ubuntu

Option 1: Using Microsoft Store (Recommended)

1. Open Microsoft Store and search for “Ubuntu”
2. Install Ubuntu 22.04 LTS (or latest LTS version)
3. Launch Ubuntu from the Start Menu

Option 2: Using Command Line

Open PowerShell as Administrator and run:

# Install WSL2 with Ubuntu
wsl --install -d Ubuntu-22.04

# Set WSL2 as default version
wsl --set-default-version 2

Step 4: Initial Ubuntu Setup

When you first launch Ubuntu, you’ll be prompted to create a user account:

# Create a username and password when prompted
# This will be your Linux user account

Update the system packages:

sudo apt update && sudo apt upgrade -y

Step 5: Install Core Dependencies

You need core Linux dependencies installed in order to install Ruby and other tools.

sudo apt-get update
sudo apt-get install -y git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev

Installing RVM & Ruby

Install additional dependencies required for RVM:

sudo apt-get install -y libgdbm-dev libncurses5-dev automake libtool bison libffi-dev

Install RVM & Ruby version 3.2.2:

# Add RVM GPG keys
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

# Install RVM
curl -sSL https://get.rvm.io | bash -s stable

# Load RVM into current session
source ~/.rvm/scripts/rvm

# Install Ruby 3.2.2
rvm install 3.2.2
rvm use 3.2.2 --default

# Verify installation
ruby -v

Install Node.js

Chatwoot requires Node.js version 20. Install Node.js from NodeSource using the following commands:

curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify Node.js installation:

node --version
# Should output: v20.x.x

Install pnpm

We use pnpm as the package manager for better performance:

# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version

Install PostgreSQL

The database used in Chatwoot is PostgreSQL. Use the following commands to install PostgreSQL:

sudo apt install -y postgresql postgresql-contrib

The installation procedure created a user account called postgres that is associated with the default Postgres role. In order to use PostgreSQL, you can log into that account:

sudo -u postgres psql

Install libpq-dev dependencies for Ubuntu:

sudo apt-get install -y libpq-dev

Start PostgreSQL service:

sudo service postgresql start

Configure PostgreSQL to start automatically:

echo 'sudo service postgresql start' >> ~/.bashrc

Create a database user:

# Switch to postgres user and create a superuser
sudo -u postgres createuser --superuser $USER

# Set password for your user
sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';"

Install Redis Server

Chatwoot uses Redis server for agent assignments and reporting. To install redis-server:

sudo apt-get install -y redis-server

Start Redis service:

sudo service redis-server start

Configure Redis to start automatically:

echo 'sudo service redis-server start' >> ~/.bashrc

Enable Redis to start on system boot:

sudo systemctl enable redis-server.service

Install ImageMagick

Chatwoot uses ImageMagick for image processing:

sudo apt-get install -y imagemagick libmagickwand-dev

Configure Git

Set up Git with your information:

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

Windows-Specific Configuration

Install VS Code with WSL Extension

1. Install Visual Studio Code on Windows from https://code.visualstudio.com/
2. Install Remote - WSL extension from the Extensions marketplace
3. Open your project in WSL by running code . from your WSL terminal

Configure File Permissions

WSL2 may have file permission issues. Fix them:

# Add to ~/.bashrc for better file permissions
echo 'umask 022' >> ~/.bashrc

# Configure Git to ignore file mode changes
git config --global core.filemode false

Environment Verification

Verify all installations are working correctly:

# Check all versions
ruby --version        # Should be 3.2.2
node --version         # Should be v20.x.x
pnpm --version        # Should show pnpm version
psql --version        # Should show PostgreSQL version
redis-cli ping        # Should output: PONG
convert --version     # Should show ImageMagick version
git --version         # Should show Git version

Troubleshooting Common Issues

WSL installation fails

Solution: Ensure virtualization is enabled in BIOS and Windows features are properly enabled:

1. Restart computer and enter BIOS settings
2. Enable Intel VT-x or AMD-V virtualization
3. Enable Hyper-V in Windows Features
4. Restart and try installation again

Ubuntu terminal won't open

Solution: Reset WSL or reinstall Ubuntu:

# Reset Ubuntu (will delete all data)
wsl --unregister Ubuntu-22.04
wsl --install -d Ubuntu-22.04

PostgreSQL fails to start

Solution: Check if Windows PostgreSQL service is conflicting:

# Stop Windows PostgreSQL service first (run in Windows Command Prompt as Admin)
net stop postgresql-x64-14

# Then start WSL2 PostgreSQL
sudo service postgresql start

Permission denied errors

Solution: Fix file permissions:

# For the entire project
find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;

# For executable files
chmod +x bin/*

Slow performance

Solution: Ensure code is stored in WSL2 filesystem:

# Good: Store code here (fast)
/home/username/projects/chatwoot

# Avoid: Storing code here (slow)
/mnt/c/Users/Username/projects/chatwoot

If you encounter issues during setup:

• Common Errors: Check Common Errors
• WSL2 Documentation: Microsoft WSL Documentation
• Discord Community: Join our Discord
• GitHub Issues: Create an issue

---

Your Windows development environment with WSL2 is now ready for Chatwoot development! 🪟🐧