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.
Open Terminal app and run:
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.
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:
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:
Verify pnpm installation:
Install PostgreSQL The database used in Chatwoot is PostgreSQL.
Option 1: PostgresApp (Recommended)
Download and install PostgresApp from https://postgresapp.com
This is the easiest way to get started with PostgreSQL on macOS
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:
Connect to PostgreSQL to verify installation:
psql postgres # Type \q to exit Install Redis Server Chatwoot uses Redis server for agent assignments and reporting:
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:
Verify ImageMagick installation:
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 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:
Your macOS development environment is now ready for Chatwoot development! 🚀 
