> ## Documentation Index
> Fetch the complete documentation index at: https://developers.chatwoot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ubuntu Development Setup

> Complete guide to setting up your Ubuntu development environment for Chatwoot contribution.

# 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:

```bash theme={null}
sudo apt-get update
```

## Install Git

Install Git for version control:

```bash theme={null}
sudo apt-get install git
```

Configure Git with your information:

```bash theme={null}
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

Verify Git installation:

```bash theme={null}
git --version
```

## Install RVM

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

```bash theme={null}
sudo apt-get install software-properties-common
```

Install RVM (Ruby Version Manager):

```bash theme={null}
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:

```bash theme={null}
rvm install ruby-3.3.3
```

Use Ruby 3.3.3 as default:

```bash theme={null}
rvm use 3.3.3 --default
```

Verify Ruby installation:

```bash theme={null}
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:

```bash theme={null}
curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```

Verify Node.js installation:

```bash theme={null}
node --version
# Should output: v20.x.x

npm --version
```

## Install pnpm

We use `pnpm` as the package manager:

```bash theme={null}
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

Verify pnpm installation:

```bash theme={null}
pnpm --version
```

## Install PostgreSQL

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

```bash theme={null}
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:

```bash theme={null}
sudo -u postgres psql
```

Install `libpq-dev` dependencies for Ubuntu:

```bash theme={null}
sudo apt-get install libpq-dev
```

Verify PostgreSQL installation:

```bash theme={null}
psql --version
```

## Install Redis Server

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

```bash theme={null}
sudo apt-get install redis-server
```

Next, enable Redis to start on system boot:

```bash theme={null}
sudo systemctl enable redis-server.service
```

Verify Redis installation:

```bash theme={null}
redis-cli ping
# Should output: PONG
```

## Install ImageMagick

Install ImageMagick for image processing:

```bash theme={null}
sudo apt-get install imagemagick
```

Verify ImageMagick installation:

```bash theme={null}
convert --version
```

## Troubleshooting Common Issues

<Accordion title="RVM installation fails">
  **Solution**: Ensure you have restarted your computer and enabled "Run command as a login shell":

  ```bash theme={null}
  # Check if RVM is loaded
  rvm --version

  # If not found, try loading manually
  source ~/.rvm/scripts/rvm
  ```
</Accordion>

<Accordion title="Ruby installation fails">
  **Solution**: Install missing dependencies:

  ```bash theme={null}
  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
  ```
</Accordion>

<Accordion title="PostgreSQL connection issues">
  **Solution**: Configure PostgreSQL user and database:

  ```bash theme={null}
  # 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
  ```
</Accordion>

<Accordion title="Node.js installation issues">
  **Solution**: Clear cache and reinstall:

  ```bash theme={null}
  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
  ```
</Accordion>

<Accordion title="Permission denied errors">
  **Solution**: Fix ownership of common directories:

  ```bash theme={null}
  sudo chown -R $USER:$USER ~/.npm
  sudo chown -R $USER:$USER ~/.pnpm-store
  ```
</Accordion>

## Getting Help

If you encounter issues:

* **Common Errors**: Check [Common Errors](/contributing-guide/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! 🐧