# Chatwoot

Chatwoot is an open source customer engagement platform with live chat, shared inboxes and AI agents

[Chatwoot](https://github.com/chatwoot/chatwoot) is an open source alternative to Intercom and Zendesk. It is a Ruby on Rails application with a Vue frontend built by Vite, and it needs PostgreSQL with the pgvector extension, Redis and Sidekiq.

## Requirements

Create a PostgreSQL database and a Redis database from the app's Databases tab. Hatchbox attaches them as `DATABASE_URL` and `REDIS_URL`.

Chatwoot's schema enables the `vector` extension, so install pgvector on the PostgreSQL server over SSH as root before the first deploy. Replace `17` with your PostgreSQL major version (`pg_lsclusters` shows it):

```
sudo apt install postgresql-17-pgvector
```

The frontend build runs Node with a 4 GB heap and peaks at nearly 5 GB of memory, so build on a server with at least 4 GB of RAM and add swap if it has only 4 GB.

## Repository

Fork Chatwoot and add the script below, then set the Git URL to your fork:

```
https://github.com/<your-user>/chatwoot.git
```

Use the `master` branch. It is Chatwoot's stable branch; `develop` is where unreleased work lands.

## Environment Variables

```
FRONTEND_URL=https://chat.example.com
HATCHBOX_SKIP_MIGRATE=true
NODE_OPTIONS=--max-old-space-size=4096 --openssl-legacy-provider
ENABLE_ACCOUNT_SIGNUP=false
```

`FRONTEND_URL` is the full URL Chatwoot is served from. `HATCHBOX_SKIP_MIGRATE` turns off Hatchbox's `db:migrate` step, because Chatwoot sets up the database with its own task (see the build script). `NODE_OPTIONS` matches the flags Chatwoot's own installer passes to the asset build. Hatchbox sets `RAILS_ENV`, `SECRET_KEY_BASE` and `RAILS_LOG_TO_STDOUT` for you.

To send email, also set `MAILER_SENDER_EMAIL`, `SMTP_ADDRESS`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_AUTHENTICATION` and `SMTP_DOMAIN`. Two-factor authentication needs `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY`, `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` and `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT`, which you can generate with `bin/rails db:encryption:init`.

## Build Scripts

Chatwoot does not support running every migration from scratch on an empty database. Its `db:chatwoot_prepare` task loads the schema and seeds on a new database and runs pending migrations on an existing one, so run it after each build on the cron server instead of `db:migrate`.

### .hatchbox/post-build

```
#!/usr/bin/env bash
set -e

if [ "$CRON" = "true" ]; then
  POSTGRES_STATEMENT_TIMEOUT=600s bundle exec rails db:chatwoot_prepare
fi
```

Hatchbox's standard Rails build handles the rest: `bundle install`, `pnpm install` and `assets:precompile`, which Chatwoot hooks to build its SDK and the Vite bundles.

## Processes

Hatchbox detects and configures the Rails server and Sidekiq automatically. Sidekiq picks up `config/sidekiq.yml` on its own. Set `SIDEKIQ_CONCURRENCY` if you want to change the default of 10 threads.

## First Login

Open your domain. A fresh install shows Chatwoot's onboarding screen where you create the super admin user and the first account. Instance-wide settings live at `/super_admin` afterwards.

## Notes

Uploads use Active Storage on local disk by default, stored in `storage/`, which Hatchbox keeps in the app's shared directory. That works on a single-server cluster. For multiple servers set `ACTIVE_STORAGE_SERVICE=amazon` with `S3_BUCKET_NAME`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_REGION`.

To update, deploy again from `master`. Chatwoot's own upgrade tooling warns against switching between branches, so stay on one.