Skip to main content

​
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

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
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
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
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
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:
Your Ubuntu development environment is now ready for Chatwoot development! 🐧
⌘I