chatwoot/developer-docs/contributing/project-setup/windows-setup.mdx

---
title: Windows Development Setup
description: Complete guide to setting up your Windows development environment for Chatwoot contribution using WSL2.
sidebarTitle: Windows Setup
---

# 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.

<img src="/contributing/project-setup/img/developer-mode.jpg" width="500" alt="Enable Developer Mode" />

## 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.

<img src="/contributing/project-setup/img/enable-wsl.jpg" width="500" alt="Enable WSL" />

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:

```powershell
# 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:

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

Update the system packages:

```bash
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.

```bash
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:

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

Install RVM & Ruby version 3.2.2:

```bash
# 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:

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

Verify Node.js installation:

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

## Install pnpm

We use `pnpm` as the package manager for better performance:

```bash
# 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:

```bash
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:

```bash
sudo -u postgres psql
```

Install `libpq-dev` dependencies for Ubuntu:

```bash
sudo apt-get install -y libpq-dev
```

Start PostgreSQL service:

```bash
sudo service postgresql start
```

Configure PostgreSQL to start automatically:

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

Create a database user:

```bash
# 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`:

```bash
sudo apt-get install -y redis-server
```

Start Redis service:

```bash
sudo service redis-server start
```

Configure Redis to start automatically:

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

Enable Redis to start on system boot:

```bash
sudo systemctl enable redis-server.service
```

## Install ImageMagick

Chatwoot uses ImageMagick for image processing:

```bash
sudo apt-get install -y imagemagick libmagickwand-dev
```

## Configure Git

Set up Git with your information:

```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

## Windows-Specific Configuration

### Install VS Code with WSL Extension

1. **Install Visual Studio Code** on Windows from [https://code.visualstudio.com/](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:

```bash
# 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:

```bash
# 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

<Accordion title="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
</Accordion>

<Accordion title="Ubuntu terminal won't open">
**Solution**: Reset WSL or reinstall Ubuntu:
```powershell
# Reset Ubuntu (will delete all data)
wsl --unregister Ubuntu-22.04
wsl --install -d Ubuntu-22.04
```
</Accordion>

<Accordion title="PostgreSQL fails to start">
**Solution**: Check if Windows PostgreSQL service is conflicting:
```bash
# 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
```
</Accordion>

<Accordion title="Permission denied errors">
**Solution**: Fix file permissions:
```bash
# For the entire project
find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;

# For executable files
chmod +x bin/*
```
</Accordion>

<Accordion title="Slow performance">
**Solution**: Ensure code is stored in WSL2 filesystem:
```bash
# Good: Store code here (fast)
/home/username/projects/chatwoot

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

If you encounter issues during setup:

- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
- **WSL2 Documentation**: [Microsoft WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/)
- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)

---

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