Ubuntu Development Setup

This guide will help you set up your Ubuntu development environment for contributing to Chatwoot. These instructions work for Ubuntu 20.04, 22.04, and newer versions.

Update System Packages

Open a terminal and run the following commands to update your system packages:

sudo apt-get update

Install Git

Install Git for version control:

sudo apt-get install git

Configure Git with your information:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Verify Git installation:

git --version

Install RVM

You need software-properties-common installed in order to add PPA repositories:

sudo apt-get install software-properties-common

Install RVM (Ruby Version Manager):

sudo apt-add-repository -y ppa:rael-gc/rvm
sudo apt-get update
sudo apt-get install rvm
sudo usermod -a -G rvm $USER

Important: Enable Run command as a login shell in terminal Preferences. Restart your computer after installation.

Install Ruby

Chatwoot APIs are built on Ruby on Rails. You need to install Ruby 3.3.3:

rvm install ruby-3.3.3

Use Ruby 3.3.3 as default:

rvm use 3.3.3 --default

Verify Ruby installation:

ruby --version
# Should output: ruby 3.3.3

Install Node.js

Chatwoot requires Node.js version 20. Install Node.js from NodeSource using the following commands:

curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify Node.js installation:

node --version
# Should output: v20.x.x

npm --version

Install pnpm

We use pnpm as the package manager:

curl -fsSL https://get.pnpm.io/install.sh | sh -

Verify pnpm installation:

pnpm --version

Install PostgreSQL

The database used in Chatwoot is PostgreSQL. Use the following commands to install PostgreSQL:

sudo apt install postgresql postgresql-contrib

The installation procedure creates a user account called postgres that is associated with the default Postgres role. In order to use Postgres, you can log into that account:

sudo -u postgres psql

Install libpq-dev dependencies for Ubuntu:

sudo apt-get install libpq-dev

Verify PostgreSQL installation:

psql --version

Install Redis Server

Chatwoot uses Redis server in agent assignments and reporting. You need to install redis-server:

sudo apt-get install redis-server

Next, enable Redis to start on system boot:

sudo systemctl enable redis-server.service

Verify Redis installation:

redis-cli ping
# Should output: PONG

Install ImageMagick

Install ImageMagick for image processing:

sudo apt-get install imagemagick

Verify ImageMagick installation:

convert --version

Troubleshooting Common Issues

RVM installation fails

Solution: Ensure you have restarted your computer and enabled “Run command as a login shell”:

# Check if RVM is loaded
rvm --version

# If not found, try loading manually
source ~/.rvm/scripts/rvm

Ruby installation fails

Solution: Install missing dependencies:

sudo apt-get install autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev
rvm reinstall ruby-3.3.3

PostgreSQL connection issues

Solution: Configure PostgreSQL user and database:

# Switch to postgres user and create a superuser
sudo -u postgres createuser --superuser $USER

# Set password for your user
sudo -u postgres psql -c "ALTER USER $USER PASSWORD 'password';"

# Create a database for your user
sudo -u postgres createdb $USER

Node.js installation issues

Solution: Clear cache and reinstall:

sudo apt-get remove nodejs npm
sudo apt-get autoremove
curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Permission denied errors

Solution: Fix ownership of common directories:

sudo chown -R $USER:$USER ~/.npm
sudo chown -R $USER:$USER ~/.pnpm-store

Getting Help

If you encounter issues:

Common Errors: Check Common Errors
Discord Community: Join our Discord
GitHub Issues: Create an issue
Ubuntu Community: Ubuntu Forums

Your Ubuntu development environment is now ready for Chatwoot development! 🐧

Getting Started

Environment Setup

Project Setup

Testing

Others

Ubuntu Development Setup

Ubuntu Development Setup

Update System Packages

Install Git

Install RVM

Install Ruby

Install Node.js

Install pnpm

Install PostgreSQL

Install Redis Server

Install ImageMagick

Troubleshooting Common Issues

Getting Help

​Ubuntu Development Setup

​Update System Packages

​Install Git

​Install RVM

​Install Ruby

​Install Node.js

​Install pnpm

​Install PostgreSQL

​Install Redis Server

​Install ImageMagick

​Troubleshooting Common Issues

​Getting Help

Ubuntu Development Setup

Update System Packages

Install Git

Install RVM

Install Ruby

Install Node.js

Install pnpm

Install PostgreSQL

Install Redis Server

Install ImageMagick

Troubleshooting Common Issues

Getting Help