---
title: Local Development Setup
description: Set up Chatwoot for local development on your machine
sidebarTitle: Local Development
---

# Local Development Setup

This guide will help you set up Chatwoot for local development on your machine. Follow these steps to get a complete development environment running.

## Prerequisites

Before setting up Chatwoot locally, ensure you have the following installed:

### Required Software

<CardGroup cols={2}>
  <Card title="Ruby" icon="gem">
    Ruby 3.3.3 (managed with rbenv or RVM)
  </Card>
  <Card title="Node.js" icon="node-js">
    Node.js 20+ with pnpm package manager
  </Card>
  <Card title="PostgreSQL" icon="database">
    PostgreSQL 13+ for the database
  </Card>
  <Card title="Redis" icon="redis">
    Redis 6+ for caching and background jobs
  </Card>
</CardGroup>

### System Dependencies

<Tabs>
  <Tab title="macOS">
    ```bash
    # Install Homebrew if not already installed
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    
    # Install dependencies
    brew install postgresql@15 redis imagemagick git
    
    # Install rbenv for Ruby version management
    brew install rbenv ruby-build
    
    # Install Node.js and pnpm
    brew install node
    npm install -g pnpm
    
    # Start services
    brew services start postgresql@15
    brew services start redis
    ```
  </Tab>
  
  <Tab title="Ubuntu/Debian">
    ```bash
    # Update package list
    sudo apt update
    
    # Install dependencies
    sudo apt install -y curl git build-essential libssl-dev libreadline-dev \
      zlib1g-dev libpq-dev imagemagick libmagickwand-dev libffi-dev \
      postgresql postgresql-contrib redis-server
    
    # Install rbenv
    curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
    
    # Install Node.js (using NodeSource)
    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    sudo apt install -y nodejs
    
    # Install pnpm
    npm install -g pnpm
    
    # Start services
    sudo systemctl start postgresql
    sudo systemctl start redis-server
    sudo systemctl enable postgresql
    sudo systemctl enable redis-server
    ```
  </Tab>
  
  <Tab title="CentOS/RHEL">
    ```bash
    # Install EPEL repository
    sudo yum install -y epel-release
    
    # Install dependencies
    sudo yum groupinstall -y "Development Tools"
    sudo yum install -y curl git openssl-devel readline-devel zlib-devel \
      postgresql-devel ImageMagick-devel libffi-devel postgresql-server \
      postgresql-contrib redis
    
    # Initialize PostgreSQL
    sudo postgresql-setup initdb
    
    # Install rbenv
    curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
    
    # Install Node.js
    curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
    sudo yum install -y nodejs
    
    # Install pnpm
    npm install -g pnpm
    
    # Start services
    sudo systemctl start postgresql
    sudo systemctl start redis
    sudo systemctl enable postgresql
    sudo systemctl enable redis
    ```
  </Tab>
</Tabs>

## Ruby Setup

### Install Ruby with rbenv

```bash
# Add rbenv to your shell profile
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Install Ruby 3.3.3
rbenv install 3.3.3
rbenv global 3.3.3

# Verify installation
ruby --version
# Should output: ruby 3.3.3

# Install bundler
gem install bundler
```

### Alternative: Using RVM

```bash
# Install RVM
curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm

# Install Ruby 3.3.3
rvm install 3.3.3
rvm use 3.3.3 --default

# Verify installation
ruby --version
gem install bundler
```

## Database Setup

### PostgreSQL Configuration

```bash
# Create PostgreSQL user (macOS with Homebrew)
createuser -s chatwoot

# Create PostgreSQL user (Linux)
sudo -u postgres createuser -s chatwoot

# Set password for the user
sudo -u postgres psql
postgres=# ALTER USER chatwoot PASSWORD 'password';
postgres=# \q

# Create databases
createdb chatwoot_development
createdb chatwoot_test
```

### PostgreSQL Authentication Setup

Edit PostgreSQL configuration to allow local connections:

```bash
# Find pg_hba.conf location
sudo -u postgres psql -c "SHOW hba_file;"

# Edit the file (example path)
sudo nano /etc/postgresql/15/main/pg_hba.conf

# Add or modify these lines:
local   all             chatwoot                                md5
host    all             chatwoot        127.0.0.1/32            md5
host    all             chatwoot        ::1/128                 md5

# Restart PostgreSQL
sudo systemctl restart postgresql
```

## Project Setup

### Clone the Repository

```bash
# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/YOUR_USERNAME/chatwoot.git
cd chatwoot

# Add upstream remote
git remote add upstream https://github.com/chatwoot/chatwoot.git

# Verify remotes
git remote -v
```

### Install Dependencies

```bash
# Install Ruby dependencies
bundle install

# Install Node.js dependencies
pnpm install

# Install Playwright for E2E tests (optional)
pnpm exec playwright install
```

### Environment Configuration

```bash
# Copy environment file
cp .env.example .env

# Edit the environment file
nano .env
```

Update the `.env` file with your local configuration:

```bash
# Database configuration
DATABASE_URL=postgresql://chatwoot:password@localhost:5432/chatwoot_development
REDIS_URL=redis://localhost:6379/0

# Application settings
FRONTEND_URL=http://localhost:3000
FORCE_SSL=false
RAILS_ENV=development
NODE_ENV=development

# Email configuration (for development)
MAILER_SENDER_EMAIL=dev@chatwoot.local
SMTP_ADDRESS=localhost
SMTP_PORT=1025

# File storage (local)
ACTIVE_STORAGE_SERVICE=local

# Development features
ENABLE_DEVELOPMENT_FEATURES=true
LOG_LEVEL=debug
```

### Database Initialization

```bash
# Create and migrate the database
bundle exec rails db:create
bundle exec rails db:migrate

# Seed the database with sample data
bundle exec rails db:seed

# Prepare the test database
RAILS_ENV=test bundle exec rails db:create
RAILS_ENV=test bundle exec rails db:migrate
```

## Running the Application

### Start Development Servers

You'll need to run multiple processes for full development:

#### Option 1: Using Foreman (Recommended)

```bash
# Install foreman
gem install foreman

# Start all services
foreman start -f Procfile.dev
```

#### Option 2: Manual Process Management

Open multiple terminal windows/tabs:

```bash
# Terminal 1: Rails server
bundle exec rails server -p 3000

# Terminal 2: Webpack dev server
pnpm run dev

# Terminal 3: Sidekiq worker
bundle exec sidekiq

# Terminal 4: MailHog (for email testing)
mailhog
```

### Access the Application

Once all services are running:

- **Web Application**: http://localhost:3000
- **API Documentation**: http://localhost:3000/swagger
- **Sidekiq Web UI**: http://localhost:3000/sidekiq
- **MailHog (Email)**: http://localhost:8025

### Default Login Credentials

After seeding the database, you can log in with:

- **Email**: john@acme.inc
- **Password**: Password1!

## Development Tools

### Code Quality Tools

```bash
# Install development gems
bundle install --with development test

# Run RuboCop (Ruby linter)
bundle exec rubocop

# Run RuboCop with auto-fix
bundle exec rubocop -a

# Run ESLint (JavaScript linter)
pnpm run lint

# Run ESLint with auto-fix
pnpm run lint:fix

# Run Prettier (code formatter)
pnpm run format
```

### Testing

```bash
# Run Ruby tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/models/user_spec.rb

# Run JavaScript tests
pnpm run test

# Run E2E tests
pnpm run test:e2e

# Run tests with coverage
COVERAGE=true bundle exec rspec
```

### Database Operations

```bash
# Reset database
bundle exec rails db:drop db:create db:migrate db:seed

# Generate migration
bundle exec rails generate migration AddColumnToTable column:type

# Run migrations
bundle exec rails db:migrate

# Rollback migration
bundle exec rails db:rollback

# Check migration status
bundle exec rails db:migrate:status
```

## IDE and Editor Setup

### VS Code Configuration

Create `.vscode/settings.json`:

```json
{
  "ruby.intellisense": "rubyLocate",
  "ruby.codeCompletion": "rcodetools",
  "ruby.format": "rubocop",
  "editor.formatOnSave": true,
  "editor.rulers": [120],
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "eslint.autoFixOnSave": true,
  "prettier.requireConfig": true
}
```

### Recommended VS Code Extensions

```json
{
  "recommendations": [
    "rebornix.ruby",
    "wingrunr21.vscode-ruby",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "ms-vscode.vscode-typescript-next",
    "bradlc.vscode-tailwindcss"
  ]
}
```

### RubyMine Configuration

1. Open the project in RubyMine
2. Configure Ruby SDK: File → Project Structure → SDKs
3. Set up database connection in Database tool window
4. Configure code style: File → Settings → Editor → Code Style

## Debugging

### Rails Debugging

```ruby
# Add to your code for debugging
binding.pry

# Or use the built-in debugger
debugger
```

### JavaScript Debugging

```javascript
// Add to your code
console.log('Debug info:', variable);
debugger;
```

### Database Debugging

```bash
# Rails console
bundle exec rails console

# Database console
bundle exec rails dbconsole

# Check database queries in logs
tail -f log/development.log | grep SQL
```

## Common Issues and Solutions

### Bundle Install Issues

<Accordion title="pg gem installation fails">
```bash
# macOS
brew install postgresql
bundle config build.pg --with-pg-config=/usr/local/bin/pg_config

# Ubuntu/Debian
sudo apt-get install libpq-dev
bundle install
```
</Accordion>

<Accordion title="ImageMagick issues">
```bash
# macOS
brew install imagemagick pkg-config

# Ubuntu/Debian
sudo apt-get install libmagickwand-dev

# Then reinstall the gem
bundle pristine rmagick
```
</Accordion>

### Node.js Issues

<Accordion title="pnpm install fails">
```bash
# Clear cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install
```
</Accordion>

<Accordion title="Webpack compilation errors">
```bash
# Clear webpack cache
rm -rf tmp/cache/webpacker
pnpm run dev
```
</Accordion>

### Database Issues

<Accordion title="Database connection refused">
```bash
# Check if PostgreSQL is running
sudo systemctl status postgresql

# Start PostgreSQL if not running
sudo systemctl start postgresql

# Check connection
psql -U chatwoot -d chatwoot_development -h localhost
```
</Accordion>

<Accordion title="Permission denied for database">
```bash
# Reset PostgreSQL user password
sudo -u postgres psql
postgres=# ALTER USER chatwoot PASSWORD 'password';
postgres=# \q
```
</Accordion>

## Performance Optimization

### Development Performance Tips

```bash
# Use spring for faster Rails commands
bundle exec spring binstub --all

# Use bootsnap for faster boot times (already included)
# Ensure tmp/cache directory exists
mkdir -p tmp/cache

# Use parallel testing
bundle exec rspec --parallel

# Optimize database queries
# Add to config/environments/development.rb
config.active_record.verbose_query_logs = true
```

### Memory Usage Optimization

```bash
# Monitor memory usage
ps aux | grep ruby
ps aux | grep node

# Use jemalloc for better memory management
export MALLOC_ARENA_MAX=2
bundle exec rails server
```

## Next Steps

Once you have your development environment set up:

1. **Read the Contributing Guidelines**: Check out the [contributing guide](../introduction) for code standards and workflow
2. **Explore the Codebase**: Familiarize yourself with the project structure
3. **Pick an Issue**: Look for "good first issue" labels on GitHub
4. **Join the Community**: Connect with other contributors on Discord or GitHub Discussions

## Getting Help

If you encounter issues during setup:

- **GitHub Issues**: Search existing issues or create a new one
- **Discord Community**: Join the Chatwoot Discord server
- **Documentation**: Check the official documentation
- **Stack Overflow**: Search for Chatwoot-related questions

---

You're now ready to start contributing to Chatwoot! The development environment should be fully functional and ready for coding.