add intro documentation and user guide
This commit is contained in:
Tanmay Deep Sharma
@@ -0,0 +1,314 @@
|
||||
---
|
||||
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! 🚀
|
||||
Reference in New Issue
Block a user