---
title: Ubuntu Development Setup
description: Complete guide to setting up your Ubuntu development environment for Chatwoot contribution.
sidebarTitle: Ubuntu Setup
---

# 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

First, update your system packages to ensure you have the latest security updates:

```bash
sudo apt update
sudo apt upgrade -y
```

## Install Essential Build Tools

Install fundamental development tools and dependencies:

```bash
sudo apt install -y curl wget gnupg2 software-properties-common apt-transport-https ca-certificates build-essential libssl-dev libreadline-dev zlib1g-dev libyaml-dev libxml2-dev libxslt-dev
```

## Install Git

Install Git for version control:

```bash
sudo apt install -y git
```

Configure Git with your information:

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

Verify Git installation:

```bash
git --version
```

## Install Ruby Version Manager (RVM)

Install RVM to manage Ruby versions:

```bash
# Install GPG keys
curl -sSL https://rvm.io/mpapis.asc | gpg --import -
curl -sSL https://rvm.io/pkuczynski.asc | gpg --import -

# Install RVM
curl -L https://get.rvm.io | bash -s stable

# Load RVM into current shell
source ~/.rvm/scripts/rvm
```

Add RVM to your shell profile:

```bash
echo 'source ~/.rvm/scripts/rvm' >> ~/.bashrc
source ~/.bashrc
```

## Install Ruby

Install Ruby 3.2.2 using RVM:

```bash
# Install Ruby 3.2.2
rvm install ruby-3.2.2

# Set as default Ruby version
rvm use 3.2.2 --default

# Verify installation
ruby --version
# Should output: ruby 3.2.2
```

## Install Node.js

Install Node.js 20 using NodeSource repository:

```bash
# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js
sudo apt install -y nodejs

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

npm --version
```

## Install pnpm

Install pnpm package manager:

```bash
# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version
```

## Install PostgreSQL

Install PostgreSQL database server:

```bash
# Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib libpq-dev

# Start and enable PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

Configure PostgreSQL:

```bash
# 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
```

Verify PostgreSQL installation:

```bash
psql --version
psql -c "SELECT version();"
```

## Install Redis

Install Redis server for background job processing:

```bash
# Install Redis
sudo apt install -y redis-server

# Start and enable Redis service
sudo systemctl start redis-server
sudo systemctl enable redis-server
```

Verify Redis installation:

```bash
redis-cli ping
# Should output: PONG
```

## Install ImageMagick

Install ImageMagick for image processing:

```bash
sudo apt install -y imagemagick libmagickwand-dev
```

Verify ImageMagick installation:

```bash
convert --version
```

## Troubleshooting Common Issues

<Accordion title="Ruby installation fails">
**Solution**: Install missing dependencies:
```bash
sudo apt install -y autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev
rvm reinstall 3.2.2
```
</Accordion>

<Accordion title="PostgreSQL authentication fails">
**Solution**: Configure peer authentication:
```bash
sudo -u postgres psql
ALTER USER postgres PASSWORD 'your_password';
\q

# Edit pg_hba.conf
sudo nano /etc/postgresql/*/main/pg_hba.conf
# Change 'peer' to 'md5' for local connections
sudo systemctl restart postgresql
```
</Accordion>

<Accordion title="Permission denied for /usr/local">
**Solution**: Fix ownership:
```bash
sudo chown -R $USER:$USER /usr/local
```
</Accordion>

<Accordion title="Node.js installation issues">
**Solution**: Use Node Version Manager (nvm):
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20
```
</Accordion>

<Accordion title="ImageMagick policy errors">
**Solution**: Update ImageMagick policy:
```bash
sudo nano /etc/ImageMagick-6/policy.xml
# Comment out or modify restrictive policies
```
</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)
- **Ubuntu Community**: [Ubuntu Forums](https://ubuntuforums.org/)

---

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