macOS Development Setup

Complete guide to setting up your macOS development environment for Chatwoot contribution.

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 "[e-mail]"

Install Ruby Version Manager

Choose between RVM or rbenv for managing Ruby versions.

Option 1: Install RVM (Recommended)

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.

Option 1: PostgresApp (Recommended)

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

Command line tools installation fails

Solution: Update macOS to the latest version and try again. You can also download Xcode from the App Store.

Homebrew installation permission errors

Solution:

sudo chown -R $(whoami) /opt/homebrew

Ruby installation fails with RVM

Solution:

# Install missing dependencies
brew install openssl readline libyaml
rvm reinstall 3.2.2 --with-openssl-dir=$(brew --prefix openssl)

PostgreSQL connection refused

Solution:

# Restart PostgreSQL
brew services restart postgresql@14

# Check if it's running
brew services list | grep postgresql

ImageMagick installation issues

Solution:

# If you encounter issues, try:
brew uninstall imagemagick
brew install imagemagick

Getting Help

If you encounter issues:

• Common Errors: Check Common Errors
• Discord Community: Join our Discord
• GitHub Issues: Create an issue

---

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

Assistant

Responses are generated using AI and may contain mistakes.