314 lines
6.2 KiB
Plaintext
314 lines
6.2 KiB
Plaintext
---
|
|
title: macOS Development Setup
|
|
description: Complete guide to setting up your macOS development environment for Chatwoot contribution.
|
|
sidebarTitle: macOS Setup
|
|
---
|
|
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
/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):
|
|
|
|
```bash
|
|
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
|
|
eval "$(/opt/homebrew/bin/brew shellenv)"
|
|
```
|
|
|
|
## Install Git
|
|
|
|
```bash
|
|
brew update
|
|
brew install git
|
|
```
|
|
|
|
Configure Git with your information:
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
curl -L https://get.rvm.io | bash -s stable
|
|
source ~/.rvm/scripts/rvm
|
|
```
|
|
|
|
### Option 2: Install rbenv (Alternative)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
rvm install ruby-3.2.2
|
|
rvm use 3.2.2 --default
|
|
source ~/.rvm/scripts/rvm
|
|
```
|
|
|
|
### If using rbenv:
|
|
|
|
```bash
|
|
rbenv install 3.2.2
|
|
rbenv global 3.2.2
|
|
```
|
|
|
|
<Info>
|
|
rbenv identifies the ruby version from `.ruby-version` file on the root of the project and loads it automatically.
|
|
</Info>
|
|
|
|
Verify Ruby installation:
|
|
|
|
```bash
|
|
ruby --version
|
|
# Should output: ruby 3.2.2
|
|
```
|
|
|
|
## Install Node.js
|
|
|
|
Chatwoot requires Node.js version 20:
|
|
|
|
```bash
|
|
brew install node@20
|
|
```
|
|
|
|
If you need to link Node.js 20:
|
|
|
|
```bash
|
|
brew link node@20
|
|
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
|
|
source ~/.zshrc
|
|
```
|
|
|
|
Verify Node.js installation:
|
|
|
|
```bash
|
|
node --version
|
|
# Should output: v20.x.x
|
|
```
|
|
|
|
## Install pnpm
|
|
|
|
We use `pnpm` as our package manager for better performance:
|
|
|
|
```bash
|
|
brew install pnpm
|
|
```
|
|
|
|
Verify pnpm installation:
|
|
|
|
```bash
|
|
pnpm --version
|
|
```
|
|
|
|
## Install PostgreSQL
|
|
|
|
The database used in Chatwoot is PostgreSQL.
|
|
|
|
### Option 1: PostgresApp (Recommended)
|
|
|
|
1. Download and install PostgresApp from [https://postgresapp.com](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
|
|
|
|
```bash
|
|
brew install postgresql@14
|
|
```
|
|
|
|
Start PostgreSQL service:
|
|
|
|
```bash
|
|
brew services start postgresql@14
|
|
```
|
|
|
|
Create a PostgreSQL user:
|
|
|
|
```bash
|
|
createuser -s postgres
|
|
```
|
|
|
|
Connect to PostgreSQL to verify installation:
|
|
|
|
```bash
|
|
psql postgres
|
|
# Type \q to exit
|
|
```
|
|
|
|
## Install Redis Server
|
|
|
|
Chatwoot uses Redis server for agent assignments and reporting:
|
|
|
|
```bash
|
|
brew install redis
|
|
```
|
|
|
|
Start the Redis service:
|
|
|
|
```bash
|
|
brew services start redis
|
|
```
|
|
|
|
Verify Redis installation:
|
|
|
|
```bash
|
|
redis-cli ping
|
|
# Should output: PONG
|
|
```
|
|
|
|
## Install ImageMagick
|
|
|
|
Chatwoot uses ImageMagick library to resize images for previews and thumbnails:
|
|
|
|
```bash
|
|
brew install imagemagick
|
|
```
|
|
|
|
Verify ImageMagick installation:
|
|
|
|
```bash
|
|
convert --version
|
|
```
|
|
|
|
## Install Additional Dependencies
|
|
|
|
Install other useful development tools:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# Install Docker Desktop
|
|
brew install --cask docker
|
|
```
|
|
|
|
Or download Docker Desktop from [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/).
|
|
|
|
## Environment Verification
|
|
|
|
Verify all installations are working:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
# 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
|
|
|
|
<Accordion title="Command line tools installation fails">
|
|
**Solution**: Update macOS to the latest version and try again. You can also download Xcode from the App Store.
|
|
</Accordion>
|
|
|
|
<Accordion title="Homebrew installation permission errors">
|
|
**Solution**:
|
|
```bash
|
|
sudo chown -R $(whoami) /opt/homebrew
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Ruby installation fails with RVM">
|
|
**Solution**:
|
|
```bash
|
|
# Install missing dependencies
|
|
brew install openssl readline libyaml
|
|
rvm reinstall 3.2.2 --with-openssl-dir=$(brew --prefix openssl)
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="PostgreSQL connection refused">
|
|
**Solution**:
|
|
```bash
|
|
# Restart PostgreSQL
|
|
brew services restart postgresql@14
|
|
|
|
# Check if it's running
|
|
brew services list | grep postgresql
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="ImageMagick installation issues">
|
|
**Solution**:
|
|
```bash
|
|
# If you encounter issues, try:
|
|
brew uninstall imagemagick
|
|
brew install imagemagick
|
|
```
|
|
</Accordion>
|
|
|
|
## Getting Help
|
|
|
|
If you encounter issues:
|
|
|
|
- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
|
|
- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
|
|
- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)
|
|
|
|
---
|
|
|
|
Your macOS development environment is now ready for Chatwoot development! 🚀 |