​
macOS Development Setup

This guide will help you set up your macOS development environment for contributing to Chatwoot. Open Terminal app and run the following commands.

​
Installing the Standalone Command Line Tools

Open Terminal app and run:

xcode-select --install

This installs essential development tools including Git, GCC, and other command line utilities.

​
Install Homebrew

Homebrew is the missing package manager for macOS:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

After installation, add Homebrew to your PATH (if not automatically added):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

​
Install Git

brew update
brew install git

Configure Git with your information:

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

​
Install Ruby Version Manager

Choose between RVM or rbenv for managing Ruby versions.

curl -L https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm

​
Option 2: Install rbenv (Alternative)

brew install rbenv ruby-build
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

​
Install Ruby

Chatwoot APIs are built on Ruby on Rails. You need to install Ruby 3.2.2.

​
If using RVM:

rvm install ruby-3.2.2
rvm use 3.2.2 --default
source ~/.rvm/scripts/rvm

​
If using rbenv:

rbenv install 3.2.2
rbenv global 3.2.2

rbenv identifies the ruby version from .ruby-version file on the root of the project and loads it automatically.

Verify Ruby installation:

ruby --version
# Should output: ruby 3.2.2

​
Install Node.js

Chatwoot requires Node.js version 20:

brew install node@20

If you need to link Node.js 20:

brew link node@20
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify Node.js installation:

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

​
Install pnpm

We use pnpm as our package manager for better performance:

brew install pnpm

Verify pnpm installation:

pnpm --version

​
Install PostgreSQL

The database used in Chatwoot is PostgreSQL.

  1. Download and install PostgresApp from https://postgresapp.com
  2. This is the easiest way to get started with PostgreSQL on macOS
  3. Follow the setup instructions on their website

​
Option 2: Homebrew Installation

brew install postgresql@14

Start PostgreSQL service:

brew services start postgresql@14

Create a PostgreSQL user:

createuser -s postgres

Connect to PostgreSQL to verify installation:

psql postgres
# Type \q to exit

​
Install Redis Server

Chatwoot uses Redis server for agent assignments and reporting:

brew install redis

Start the Redis service:

brew services start redis

Verify Redis installation:

redis-cli ping
# Should output: PONG

​
Install ImageMagick

Chatwoot uses ImageMagick library to resize images for previews and thumbnails:

brew install imagemagick

Verify ImageMagick installation:

convert --version

​
Install Additional Dependencies

Install other useful development tools:

# Install Yarn (alternative to pnpm if needed)
brew install yarn

# Install SQLite (for testing)
brew install sqlite

# Install libvips (for image processing)
brew install libvips

​
Install Docker (Optional)

For development and testing with containers:

# Install Docker Desktop
brew install --cask docker

Or download Docker Desktop from https://www.docker.com/products/docker-desktop/.

​
Environment Verification

Verify all installations are working:

# Check 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 --version   # Should show Redis version
convert --version     # Should show ImageMagick version
git --version         # Should show Git version

​
Configure Shell Environment

Add useful aliases to your shell configuration file (~/.zshrc for Zsh):

# Add to ~/.zshrc
echo '# Chatwoot Development Aliases' >> ~/.zshrc
echo 'alias cw-server="bundle exec rails server"' >> ~/.zshrc
echo 'alias cw-console="bundle exec rails console"' >> ~/.zshrc
echo 'alias cw-test="bundle exec rspec"' >> ~/.zshrc
echo 'alias cw-migrate="bundle exec rails db:migrate"' >> ~/.zshrc

# Reload shell configuration
source ~/.zshrc

​
Troubleshooting Common Issues

​
Getting Help

If you encounter issues:

Your macOS development environment is now ready for Chatwoot development! 🚀