docker.recipes

Chatwoot Customer Support

intermediate

Chatwoot omnichannel customer support platform with live chat and ticketing.

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.

Key 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

Common Use Cases

  • 1E-commerce websites needing embedded live chat with order tracking and customer history integration
  • 2SaaS companies requiring multi-channel support desk with API integration for user account management
  • 3Development agencies building customer support solutions for clients with white-label requirements
  • 4Small to medium businesses transitioning from expensive hosted solutions like Intercom or Zendesk
  • 5Organizations with strict data privacy requirements needing self-hosted customer communication platforms
  • 6Customer success teams managing high-volume support across multiple communication channels
  • 7Companies 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  chatwoot: 
3    image: chatwoot/chatwoot:latest
4    container_name: chatwoot
5    command: bundle exec rails s -p 3000 -b 0.0.0.0
6    environment: 
7      - RAILS_ENV=production
8      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
9      - FRONTEND_URL=${FRONTEND_URL}
10      - POSTGRES_HOST=postgres
11      - POSTGRES_DATABASE=chatwoot
12      - POSTGRES_USERNAME=${POSTGRES_USER}
13      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
14      - REDIS_URL=redis://redis:6379
15      - RAILS_LOG_TO_STDOUT=true
16    ports: 
17      - "3000:3000"
18    depends_on: 
19      postgres: 
20        condition: service_healthy
21      redis: 
22        condition: service_started
23    networks: 
24      - chatwoot-network
25
26  sidekiq: 
27    image: chatwoot/chatwoot:latest
28    container_name: chatwoot-sidekiq
29    command: bundle exec sidekiq -C config/sidekiq.yml
30    environment: 
31      - RAILS_ENV=production
32      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
33      - POSTGRES_HOST=postgres
34      - POSTGRES_DATABASE=chatwoot
35      - POSTGRES_USERNAME=${POSTGRES_USER}
36      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
37      - REDIS_URL=redis://redis:6379
38    depends_on: 
39      - chatwoot
40    networks: 
41      - chatwoot-network
42
43  postgres: 
44    image: postgres:16-alpine
45    container_name: chatwoot-db
46    environment: 
47      - POSTGRES_USER=${POSTGRES_USER}
48      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
49      - POSTGRES_DB=chatwoot
50    volumes: 
51      - postgres_data:/var/lib/postgresql/data
52    healthcheck: 
53      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
54      interval: 10s
55      timeout: 5s
56      retries: 5
57    networks: 
58      - chatwoot-network
59
60  redis: 
61    image: redis:7-alpine
62    container_name: chatwoot-redis
63    volumes: 
64      - redis_data:/data
65    networks: 
66      - chatwoot-network
67
68volumes: 
69  postgres_data: 
70  redis_data: 
71
72networks: 
73  chatwoot-network: 
74    driver: bridge

.env Template

.env
1# Chatwoot
2SECRET_KEY_BASE=your-secret-key-base-at-least-64-chars
3FRONTEND_URL=http://localhost:3000
4POSTGRES_USER=chatwoot
5POSTGRES_PASSWORD=chatwoot_password

Usage Notes

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

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

chatwoot
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
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
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
redis:
  image: redis:7-alpine
  container_name: chatwoot-redis
  volumes:
    - redis_data:/data
  networks:
    - chatwoot-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  chatwoot:
5    image: chatwoot/chatwoot:latest
6    container_name: chatwoot
7    command: bundle exec rails s -p 3000 -b 0.0.0.0
8    environment:
9      - RAILS_ENV=production
10      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
11      - FRONTEND_URL=${FRONTEND_URL}
12      - POSTGRES_HOST=postgres
13      - POSTGRES_DATABASE=chatwoot
14      - POSTGRES_USERNAME=${POSTGRES_USER}
15      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
16      - REDIS_URL=redis://redis:6379
17      - RAILS_LOG_TO_STDOUT=true
18    ports:
19      - "3000:3000"
20    depends_on:
21      postgres:
22        condition: service_healthy
23      redis:
24        condition: service_started
25    networks:
26      - chatwoot-network
27
28  sidekiq:
29    image: chatwoot/chatwoot:latest
30    container_name: chatwoot-sidekiq
31    command: bundle exec sidekiq -C config/sidekiq.yml
32    environment:
33      - RAILS_ENV=production
34      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
35      - POSTGRES_HOST=postgres
36      - POSTGRES_DATABASE=chatwoot
37      - POSTGRES_USERNAME=${POSTGRES_USER}
38      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
39      - REDIS_URL=redis://redis:6379
40    depends_on:
41      - chatwoot
42    networks:
43      - chatwoot-network
44
45  postgres:
46    image: postgres:16-alpine
47    container_name: chatwoot-db
48    environment:
49      - POSTGRES_USER=${POSTGRES_USER}
50      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
51      - POSTGRES_DB=chatwoot
52    volumes:
53      - postgres_data:/var/lib/postgresql/data
54    healthcheck:
55      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
56      interval: 10s
57      timeout: 5s
58      retries: 5
59    networks:
60      - chatwoot-network
61
62  redis:
63    image: redis:7-alpine
64    container_name: chatwoot-redis
65    volumes:
66      - redis_data:/data
67    networks:
68      - chatwoot-network
69
70volumes:
71  postgres_data:
72  redis_data:
73
74networks:
75  chatwoot-network:
76    driver: bridge
77EOF
78
79# 2. Create the .env file
80cat > .env << 'EOF'
81# Chatwoot
82SECRET_KEY_BASE=your-secret-key-base-at-least-64-chars
83FRONTEND_URL=http://localhost:3000
84POSTGRES_USER=chatwoot
85POSTGRES_PASSWORD=chatwoot_password
86EOF
87
88# 3. Start the services
89docker compose up -d
90
91# 4. View logs
92docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/chatwoot-support/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

chatwootpostgresredissidekiq

Tags

#chatwoot#support#live-chat#helpdesk#intercom-alternative

Category

Message Queues & Brokers

Related Recipes

Ad Space