Chatwoot Customer Support Installation

Chatwoot is an open-source customer support and engagement platform providing omnichannel communication through email, chat, social media, and SMS. With agent collaboration features, customer segmentation, and automation, Chatwoot enables responsive customer support. This guide covers Docker Compose deployment, PostgreSQL and Redis setup, Nginx configuration, email channel configuration, and team management.

Table of Contents

Prerequisites

Ensure you have:

  • Ubuntu 20.04 LTS or later
  • Root or sudo access
  • A registered domain name
  • Minimum 4GB RAM (8GB+ recommended)
  • 30GB available disk space
  • Basic Linux administration knowledge

Update system:

sudo apt update && sudo apt upgrade -y

System Requirements

Verify system specifications:

Check OS version:

cat /etc/os-release
uname -m

Check available resources:

free -h
df -h

Docker Installation

Install Docker and Docker Compose:

sudo apt install -y docker.io docker-compose

Add user to docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify installation:

docker --version
docker-compose --version

Start Docker:

sudo systemctl start docker
sudo systemctl enable docker

PostgreSQL and Redis Setup

Create data directories:

sudo mkdir -p /var/lib/postgresql-chatwoot
sudo mkdir -p /var/lib/redis-chatwoot
sudo chown -R $USER:$USER /var/lib/postgresql-chatwoot
sudo chown -R $USER:$USER /var/lib/redis-chatwoot

Create PostgreSQL container:

docker run -d \
  --name postgres-chatwoot \
  -e POSTGRES_DB=chatwoot \
  -e POSTGRES_USER=chatwoot \
  -e POSTGRES_PASSWORD=SecurePassword123! \
  -v /var/lib/postgresql-chatwoot:/var/lib/postgresql/data \
  postgres:13-alpine

Create Redis container:

docker run -d \
  --name redis-chatwoot \
  -v /var/lib/redis-chatwoot:/data \
  redis:7-alpine redis-server --appendonly yes

Verify containers:

docker ps | grep postgres
docker ps | grep redis

Chatwoot Deployment

Create Chatwoot directory:

mkdir -p /opt/chatwoot
cd /opt/chatwoot

Create docker-compose.yml:

nano docker-compose.yml

Add configuration:

version: '3'

services:
  chatwoot:
    image: chatwoot/chatwoot:latest
    restart: always
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://chatwoot:SecurePassword123!@postgres-chatwoot:5432/chatwoot
      REDIS_URL: redis://redis-chatwoot:6379/0
      SECRET_KEY_BASE: $(openssl rand -hex 32)
      NODE_ENV: production
      RAILS_ENV: production
      ASSET_CDN_HOST: https://support.example.com
      ACTIVE_STORAGE_SERVICE: local
      ENABLE_ACCOUNT_SIGNUP: "false"
      INVITE_USERS: "true"
      SMTP_ADDRESS: smtp.example.com
      SMTP_PORT: 587
      SMTP_USERNAME: [email protected]
      SMTP_PASSWORD: your-app-password
      SMTP_AUTHENTICATION: plain
      SMTP_ENABLE_STARTTLS_AUTO: "true"
      MAILER_SENDER_EMAIL: [email protected]
    volumes:
      - /opt/chatwoot/storage:/app/storage
      - /opt/chatwoot/public:/app/public
    depends_on:
      - postgres-chatwoot
      - redis-chatwoot
    networks:
      - chatwoot

  postgres-chatwoot:
    image: postgres:13-alpine
    restart: always
    environment:
      POSTGRES_DB: chatwoot
      POSTGRES_USER: chatwoot
      POSTGRES_PASSWORD: SecurePassword123!
    volumes:
      - /var/lib/postgresql-chatwoot:/var/lib/postgresql/data
    networks:
      - chatwoot

  redis-chatwoot:
    image: redis:7-alpine
    restart: always
    volumes:
      - /var/lib/redis-chatwoot:/data
    networks:
      - chatwoot

networks:
  chatwoot:
    driver: bridge

Create data directories:

mkdir -p /opt/chatwoot/{storage,public}

Start Chatwoot containers:

docker-compose up -d

Initialize database:

docker-compose exec chatwoot rails db:migrate
docker-compose exec chatwoot rails db:seed

Verify containers:

docker-compose ps
docker-compose logs -f chatwoot

Wait for initialization to complete.

Nginx Configuration

Install Nginx:

sudo apt install -y nginx

Create Nginx configuration:

sudo nano /etc/nginx/sites-available/chatwoot

Add configuration:

upstream chatwoot {
    server localhost:3000;
}

server {
    listen 80;
    listen [::]:80;
    server_name support.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name support.example.com;

    ssl_certificate /etc/letsencrypt/live/support.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/support.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    client_max_body_size 100M;

    location / {
        proxy_pass http://chatwoot;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }

    location /cable {
        proxy_pass http://chatwoot;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }
}

Enable site:

sudo ln -s /etc/nginx/sites-available/chatwoot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl start nginx
sudo systemctl enable nginx

SSL Certificate Setup

Install Certbot:

sudo apt install -y certbot python3-certbot-nginx

Obtain SSL certificate:

sudo certbot certonly --standalone -d support.example.com

Verify certificate:

sudo openssl x509 -in /etc/letsencrypt/live/support.example.com/fullchain.pem -noout -dates

Set up auto-renewal:

sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer

Email Channel Configuration

Access Chatwoot:

Navigate to https://support.example.com

Create admin account:

  1. Complete initial setup
  2. Create admin email and password
  3. Configure account settings

Add email channel:

  1. Click "Inbox" → "Settings"
  2. Click "Add Channel"
  3. Select "Email"
  4. Configure email settings:
    • IMAP settings
    • SMTP settings
    • Email address

Configure forwarding email:

  1. Point your support email to Chatwoot IMAP
  2. Configure mailbox rules
  3. Test email delivery

Add custom domain:

  1. Settings → Account
  2. Configure custom domain
  3. Set up CNAME records
  4. Enable SSL for custom domain

Team Setup

Create teams:

  1. Settings → Teams
  2. Click "New Team"
  3. Set team name and description

Add agents:

  1. Settings → Team Members
  2. Click "Invite Agent"
  3. Enter email address
  4. Set role (Administrator, Agent)

Configure agent permissions:

  1. Select agent
  2. Set access level
  3. Assign to specific inboxes

Create labels:

  1. Settings → Labels
  2. Create conversation labels
  3. Organize conversations

Set up automation:

  1. Settings → Automation Rules
  2. Create new automation
  3. Set conditions and actions

Backup Strategy

Create backup script:

sudo nano /usr/local/bin/chatwoot-backup.sh

Add:

#!/bin/bash

BACKUP_DIR="/backups/chatwoot"
CHATWOOT_DIR="/opt/chatwoot"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Database backup
docker exec postgres-chatwoot pg_dump -U chatwoot chatwoot | gzip > "$BACKUP_DIR/chatwoot-db-$DATE.sql.gz"

# Storage backup
tar -czf "$BACKUP_DIR/chatwoot-storage-$DATE.tar.gz" "$CHATWOOT_DIR/storage"

# Keep only 30 days
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completed: $DATE"

Make executable:

sudo chmod +x /usr/local/bin/chatwoot-backup.sh

Schedule daily backups:

sudo crontab -e

Add:

0 2 * * * /usr/local/bin/chatwoot-backup.sh >> /var/log/chatwoot-backup.log 2>&1

Update Chatwoot:

cd /opt/chatwoot
docker-compose pull
docker-compose down
docker-compose up -d
docker-compose exec chatwoot rails db:migrate

Monitor logs:

docker-compose logs -f chatwoot

Conclusion

Chatwoot is now fully deployed as a customer support platform. With PostgreSQL database, Redis caching, Nginx reverse proxy, SSL encryption, and omnichannel capabilities, you have a comprehensive support solution. Configure email channels, create teams, and manage conversations efficiently. Automate support workflows and track agent performance. Regular backups ensure data protection and business continuity. Chatwoot enables responsive, organized customer support at scale.