Development Environment Setup

Set up your local development environment for Chatwoot

This guide will help you set up a local development environment for Chatwoot.

Prerequisites

Required Software

• Ruby: Version 3.4.4 (specified in .ruby-version)
• Node.js: Version 24.x
• pnpm: Version 10.x
• PostgreSQL: Version 12 or higher
• Redis: Version 6 or higher
• rbenv: For Ruby version management

Optional Tools

• Overmind: Process manager for running multiple services (recommended)
• Foreman: Alternative process manager

Step-by-Step Setup

1. Install Ruby

Use rbenv to manage Ruby versions:

# Install rbenv (if not already installed)
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-installer | bash

# Install the required Ruby version
rbenv install $(cat .ruby-version)

# Initialize rbenv in your shell
eval "$(rbenv init -)"

Always run eval "$(rbenv init -)" before executing any bundle or rspec commands to ensure the correct Ruby and Bundler versions are used.

2. Install Node.js and pnpm

Install Node.js 24.x and pnpm 10.x:

# Using nvm (Node Version Manager)
nvm install 24
nvm use 24

# Install pnpm globally
npm install -g pnpm@10

3. Install PostgreSQL and Redis

macOS (using Homebrew):

brew install postgresql redis
brew services start postgresql
brew services start redis

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install postgresql postgresql-contrib redis-server
sudo systemctl start postgresql
sudo systemctl start redis-server

4. Clone the Repository

git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot

5. Install Dependencies

Install both Ruby and JavaScript dependencies:

bundle install && pnpm install

6. Set Up the Database

Create and set up the database:

# Create database
bundle exec rails db:create

# Run migrations
bundle exec rails db:migrate

# Seed with test data
bundle exec rails db:seed

7. Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit the .env file with your local configuration. At minimum, you’ll need:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=chatwoot_dev
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=

# Redis
REDIS_URL=redis://localhost:6379

# Frontend URL
FRONTEND_URL=http://localhost:3000

See the environment variables documentation for all available options.

Running the Application

Option 1: Using Overmind (Recommended)

Overmind is the recommended way to run all services:

overmind start -f Procfile.dev

This starts:

• Rails server
• Vite dev server (for frontend assets)
• Sidekiq (background jobs)
• Other required services

Option 2: Using pnpm

pnpm dev

This is an alias for overmind start -f Procfile.dev.

Option 3: Using Foreman

foreman start -f Procfile.dev

Option 4: Running Services Individually

In separate terminal windows:

# Terminal 1: Rails server
bundle exec rails server

# Terminal 2: Vite dev server
pnpm vite dev

# Terminal 3: Sidekiq
bundle exec sidekiq

Accessing the Application

Once running, access Chatwoot at:

• Application: http://localhost:3000
• Vite dev server: http://localhost:5173

Default login credentials (after seeding):

• Email: Check the console output after running rails db:seed
• Password: Check the console output after running rails db:seed

Seeding Test Data

Chatwoot provides multiple seeding options:

Basic Test Data

Quickly populate minimal data for standard feature verification:

bundle exec rails db:seed

Search Test Data

Bulk fixture generation for search/performance/manual load scenarios:

bundle exec rails search:setup_test_data

Account Sample Data (Richer Test Data)

The Seeders::AccountSeeder provides richer test data:

Via Super Admin UI:

1. Log in as Super Admin
2. Navigate to Accounts
3. Click “Seed” (enqueues Internal::SeedAccountJob)

Via CLI:

bundle exec rails runner "Internal::SeedAccountJob.perform_now(Account.find(<id>))"

# Or call the seeder directly
bundle exec rails runner "Seeders::AccountSeeder.new(account: Account.find(<id>)).perform!"

Codex Worktree Workflow (Advanced)

For working on multiple features simultaneously:

• Use a separate git worktree + branch per task
• Keep Codex-specific setup under .codex/
• Use Procfile.worktree for process orchestration
• Dynamically generate per-worktree DB/port values to avoid collisions
• Start each worktree with its own Overmind socket/title

Troubleshooting

Bundle Install Fails

Ensure you have the correct Ruby version:

ruby -v  # Should match .ruby-version
eval "$(rbenv init -)"
bundle install

Database Connection Issues

Verify PostgreSQL is running:

# macOS
brew services list

# Linux
sudo systemctl status postgresql

Check your .env file for correct database credentials.

Redis Connection Issues

Verify Redis is running:

# macOS
brew services list

# Linux
sudo systemctl status redis-server

# Test connection
redis-cli ping  # Should return PONG

Port Already in Use

If port 3000 is already in use:

# Find the process
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

Vite Build Issues

Clear the cache and reinstall:

rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

Next Steps

Now that your environment is set up:

1. Read the Code Style Guide
2. Learn about Testing
3. Check out open issues to find something to work on
4. Join the Discord community to connect with other contributors