​
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! 🚀