# Chatwoot Customer Support

> Chatwoot omnichannel customer support platform with live chat and ticketing.

- Category: Message Queues & Brokers
- Difficulty: intermediate
- Components: chatwoot, postgres, redis, sidekiq
- Tags: chatwoot, support, live-chat, helpdesk, intercom-alternative
- Source: https://docker.recipes/messaging/chatwoot-support

## Overview

Chatwoot is an open-source customer engagement platform that provides omnichannel support capabilities including live chat, email integration, social media messaging, and ticketing systems. Built with Ruby on Rails, it serves as a comprehensive alternative to commercial platforms like Intercom, Zendesk, or Freshchat, offering businesses full control over their customer support infrastructure. The platform emphasizes real-time communication with features like automated chatbots, conversation routing, and team collaboration tools.

This Docker stack combines Chatwoot's Rails application with PostgreSQL for persistent data storage, Redis for session management and real-time features, and Sidekiq for background job processing. PostgreSQL handles all customer conversations, contact information, and support ticket data with ACID compliance, while Redis powers the real-time chat functionality, caching, and message queuing. Sidekiq processes background tasks like email notifications, webhook deliveries, and conversation assignments asynchronously to maintain responsive user experience.

This configuration is ideal for businesses transitioning from hosted support solutions to self-hosted alternatives, development teams building customer-facing applications that need embedded chat widgets, and organizations requiring data sovereignty for customer communications. The stack provides enterprise-grade customer support capabilities while maintaining complete control over sensitive customer data and conversation histories.

## Features

- Omnichannel conversation management supporting email, chat widgets, Facebook Messenger, WhatsApp, and Twitter DMs in unified interface
- Real-time chat functionality powered by Redis Pub/Sub for instant message delivery and presence indicators
- PostgreSQL-backed conversation history with full-text search across all customer interactions and support tickets
- Sidekiq background job processing for email notifications, webhook deliveries, and automated conversation routing
- Built-in automation rules engine for conversation assignment, canned responses, and escalation workflows
- Embeddable JavaScript chat widget with customizable appearance and behavior for website integration
- Team collaboration features including private notes, conversation assignments, and agent status management
- RESTful API and webhook system for integrating with CRM systems, analytics platforms, and custom applications

## Use cases

- E-commerce websites needing embedded live chat with order tracking and customer history integration
- SaaS companies requiring multi-channel support desk with API integration for user account management
- Development agencies building customer support solutions for clients with white-label requirements
- Small to medium businesses transitioning from expensive hosted solutions like Intercom or Zendesk
- Organizations with strict data privacy requirements needing self-hosted customer communication platforms
- Customer success teams managing high-volume support across multiple communication channels
- Companies integrating customer support directly into existing Rails or web applications via API

## Prerequisites

- Minimum 2GB RAM recommended (PostgreSQL 1GB, Redis 512MB, Chatwoot 512MB for moderate traffic)
- Port 3000 available for Chatwoot web interface access
- Basic understanding of Rails application configuration and environment variables
- PostgreSQL knowledge for database maintenance, backups, and performance tuning
- Redis familiarity for monitoring memory usage and configuring persistence options
- Email SMTP server credentials for outbound customer notification emails

## docker-compose.yml

```yaml
services:
  chatwoot:
    image: chatwoot/chatwoot:latest
    container_name: chatwoot
    command: bundle exec rails s -p 3000 -b 0.0.0.0
    environment:
      - RAILS_ENV=production
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
      - FRONTEND_URL=${FRONTEND_URL}
      - POSTGRES_HOST=postgres
      - POSTGRES_DATABASE=chatwoot
      - POSTGRES_USERNAME=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - REDIS_URL=redis://redis:6379
      - RAILS_LOG_TO_STDOUT=true
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - chatwoot-network

  sidekiq:
    image: chatwoot/chatwoot:latest
    container_name: chatwoot-sidekiq
    command: bundle exec sidekiq -C config/sidekiq.yml
    environment:
      - RAILS_ENV=production
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
      - POSTGRES_HOST=postgres
      - POSTGRES_DATABASE=chatwoot
      - POSTGRES_USERNAME=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - REDIS_URL=redis://redis:6379
    depends_on:
      - chatwoot
    networks:
      - chatwoot-network

  postgres:
    image: postgres:16-alpine
    container_name: chatwoot-db
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=chatwoot
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - chatwoot-network

  redis:
    image: redis:7-alpine
    container_name: chatwoot-redis
    volumes:
      - redis_data:/data
    networks:
      - chatwoot-network

volumes:
  postgres_data:
  redis_data:

networks:
  chatwoot-network:
    driver: bridge
```

## .env

```bash
# Chatwoot
SECRET_KEY_BASE=your-secret-key-base-at-least-64-chars
FRONTEND_URL=http://localhost:3000
POSTGRES_USER=chatwoot
POSTGRES_PASSWORD=chatwoot_password
```

## Usage notes

- Dashboard at http://localhost:3000
- Run migrations first time
- Supports email, chat, social channels
- Embeddable chat widget
- Built-in automation rules

## Troubleshooting

- Chatwoot container fails with 'database does not exist': Run 'docker exec chatwoot bundle exec rails db:create db:migrate' to initialize PostgreSQL schema
- Sidekiq workers not processing jobs: Verify Redis connectivity and check Sidekiq logs with 'docker logs chatwoot-sidekiq' for job failures
- Real-time chat messages not appearing: Ensure Redis is accessible and check browser WebSocket connections in developer tools network tab
- PostgreSQL connection refused errors: Wait for health check completion or verify POSTGRES_USER/POSTGRES_PASSWORD environment variables match
- Chat widget not loading on website: Check FRONTEND_URL environment variable matches your domain and verify CORS settings
- High memory usage from Redis: Configure maxmemory policy in Redis and monitor conversation volume for appropriate resource allocation

