Chatwoot Deployment and Usage Guide

1. Prerequisites

Before installing Chatwoot, ensure your system meets these requirements:

Runtime & Database:

Ruby 3.2.2
PostgreSQL 12+ (with pgcrypto, pg_trgm, and pg_stat_statements extensions)
Redis 7+
Node.js 18+
Yarn 1.x

System Tools:

Git
ImageMagick (for image processing)
libvips (alternative image processor)
A supported SMTP service (SendGrid, Amazon SES, etc.) for email functionality

Optional (for specific features):

Cloud storage (S3, Google Cloud Storage, or Azure) for file attachments
SSL certificate for production deployment
Domain name for web access

2. Installation

Clone the Repository

git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot

Install Dependencies

# Install Ruby dependencies
bundle install

# Install JavaScript dependencies
yarn

Database Setup

# Create and setup the database
bundle exec rails db:create
bundle exec rails db:reset

The database schema includes tables for accounts, users, messages, conversations, inboxes, and supporting models as shown in the migration file.

3. Configuration

Environment Variables

Create .env file from the example:

cp .env.example .env

Essential Configuration:

# Database
DATABASE_URL=postgresql://localhost/chatwoot_development
REDIS_URL=redis://localhost:6379

# Application
SECRET_KEY_BASE=generate_with_rails_secret
FRONTEND_URL=http://localhost:3000
FORCE_SSL=false

# Email (required for user authentication)
MAILER_SENDER_EMAIL=Chatwoot <accounts@yourdomain.com>
SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your_email@gmail.com
SMTP_PASSWORD=your_password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true

# File Storage (defaults to local)
ACTIVE_STORAGE_SERVICE=local

Optional Configuration:

# Multi-tenant domain (if hosting for multiple organizations)
CHATWOOT_INSTALLATION_NAME=Chatwoot
ENABLE_ACCOUNT_SIGNUP=true

# Third-party integrations
FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
TWITTER_APP_ID=your_app_id
TWITTER_APP_SECRET=your_app_secret

Devise Authentication Configuration

The application uses devise_token_auth for authentication. Key routes are configured in config/routes.rb:

mount_devise_token_auth_for 'User', at: 'auth', controllers: {
  confirmations: 'devise_overrides/confirmations',
  passwords: 'devise_overrides/passwords',
  sessions: 'devise_overrides/sessions',
  token_validations: 'devise_overrides/token_validations',
  omniauth_callbacks: 'devise_overrides/omniauth_callbacks'
}

4. Build & Run

Development Mode

# Start Redis and PostgreSQL services first

# Compile assets
bundle exec rails assets:precompile

# Start the Rails server
bundle exec rails s -p 3000

# In another terminal, start the webpack dev server
bin/webpack-dev-server

Access the application at http://localhost:3000

Production Mode

# Precompile assets
RAILS_ENV=production bundle exec rails assets:precompile

# Run database migrations
RAILS_ENV=production bundle exec rails db:migrate

# Start the server
RAILS_ENV=production bundle exec rails s -p 3000

Using Docker (Alternative)

docker pull chatwoot/chatwoot
docker run --name chatwoot -p 3000:3000 chatwoot/chatwoot

5. Deployment

Recommended Platforms

Heroku (One-click deployment):

DigitalOcean (Managed app):

Kubernetes (via Helm):

helm repo add chatwoot https://chatwoot.github.io/charts
helm install chatwoot chatwoot/chatwoot

Manual Deployment:

Prepare the server:

# Install required system packages
sudo apt-get update
sudo apt-get install -y postgresql redis-server imagemagick libvips

Set up the application:

# Clone and install
git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot
bundle install --deployment --without development test
yarn install --production

# Configure environment
cp .env.example .env
# Edit .env with production values

Configure web server (Nginx example):

server {
  listen 80;
  server_name yourdomain.com;
  
  location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Set up process manager (Systemd example):

[Unit]
Description=Chatwoot Application Server
After=network.target postgresql.service redis-server.service

[Service]
Type=simple
User=chatwoot
WorkingDirectory=/home/chatwoot/chatwoot
Environment=RAILS_ENV=production
ExecStart=/usr/bin/bundle exec rails s -p 3000
Restart=always

[Install]
WantedBy=multi-user.target

6. Troubleshooting

Common Issues

Database connection errors:

# Ensure PostgreSQL is running
sudo systemctl status postgresql

# Check database user permissions
sudo -u postgres psql -c "\l"

Asset compilation failures:

# Clear existing assets
rake assets:clobber

# Reinstall node modules
rm -rf node_modules
yarn install

# Recompile
RAILS_ENV=production bundle exec rails assets:precompile

Email not sending:

Verify SMTP settings in .env
Check spam folder

Test with rails console:

ActionMailer::Base.mail(to: "test@example.com", subject: "Test", body: "Test").deliver_now

Authentication issues:

Ensure SECRET_KEY_BASE is set and consistent
Check Devise configuration in config/initializers/devise.rb
Verify Redis is running for session storage

WebSocket connections failing:

Ensure FRONTEND_URL is correctly set

Configure proxy to support WebSockets:

location /cable {
  proxy_pass http://localhost:3000;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "Upgrade";
}

Getting logs:

# Application logs
tail -f log/production.log

# System logs
sudo journalctl -u chatwoot.service -f

Reset the installation:

# Clear database and start fresh
bundle exec rails db:reset
bundle exec rails db:seed

For additional help, consult the official documentation or join the Discord community.

How to Deploy & Use chatwoot