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.