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, which needs a superuser to create, so install pgvector on the PostgreSQL server over SSH as root and create it in the app's database before the first deploy. Replace 17 with your PostgreSQL major version (pg_lsclusters shows it) and chatwoot with your database's name:

sudo apt install postgresql-17-pgvector
sudo -u postgres psql -d chatwoot -c "CREATE EXTENSION vector;"

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.