Skip to content
Klutch.sh Docs

Deploying a Chatwoot App

Introduction

Chatwoot is an open-source customer engagement platform that enables businesses to manage conversations across multiple channels including email, social media, live chat, and more. Built with Ruby on Rails and Vue.js, Chatwoot provides a unified inbox for customer support teams, real-time conversation management, automation capabilities, and comprehensive analytics.

Deploying Chatwoot on Klutch.sh gives you a reliable, scalable infrastructure for your customer support operations. Klutch.sh automatically detects and builds from your Dockerfile, handles HTTPS routing, and provides persistent storage for your conversation data, file uploads, and database. With support for both HTTP and TCP traffic routing, environment variable management, and easy scaling options, you can focus on delivering exceptional customer service while Klutch.sh manages the infrastructure.

This comprehensive guide walks you through deploying Chatwoot using a Dockerfile on Klutch.sh, from initial setup to production-ready configuration.

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub account and repository for your Chatwoot deployment
  • Basic understanding of Docker and containerization
  • Familiarity with environment variables and web application configuration
  • (Recommended for production) A PostgreSQL database instance

Understanding Chatwoot Architecture

Chatwoot consists of several components:

  • Rails API Server: Backend application handling business logic and data
  • Sidekiq Workers: Background job processing for async tasks
  • PostgreSQL Database: Primary data storage
  • Redis: Caching and real-time features
  • File Storage: For attachments, avatars, and media files

For a production deployment, you’ll typically run the Rails server as your main application on Klutch.sh, with separate services for PostgreSQL and Redis.

Repository Setup

    1. Create a new GitHub repository for your Chatwoot deployment or fork the official Chatwoot repository.

    2. Clone the repository to your local machine:

      Terminal window
      git clone https://github.com/your-username/chatwoot-deploy.git
      cd chatwoot-deploy

    3. Create your Dockerfile in the root directory (see the next section for sample code).

    4. Commit and push your changes to GitHub:

      Terminal window
      git add .
      git commit -m "Add Dockerfile for Klutch.sh deployment"
      git push origin main

Important: Keep sensitive data like database credentials, API keys, and secret tokens out of your repository. These will be configured as environment variables in Klutch.sh.

Sample Dockerfile

Klutch.sh automatically detects a Dockerfile when present in the root directory of your repository. Here’s a production-ready Dockerfile for Chatwoot:

Basic Dockerfile (Using Official Image)

# Use the official Chatwoot image as base
FROM chatwoot/chatwoot:latest


# Set working directory
WORKDIR /app


# Expose the default Chatwoot port
EXPOSE 3000


# The official image already includes the start command
# Default: bundle exec rails s -p 3000 -b 0.0.0.0

Advanced Dockerfile (Custom Build)

For more control over dependencies and configuration:

# Use Ruby base image
FROM ruby:3.2-slim


# Install dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    git \
    nodejs \
    npm \
    postgresql-client \
    imagemagick \
    curl \
    && rm -rf /var/lib/apt/lists/*


# Set working directory
WORKDIR /app


# Copy Gemfile and install gems
COPY Gemfile Gemfile.lock ./
RUN bundle install --jobs 4 --retry 3


# Copy package files and install Node dependencies
COPY package.json yarn.lock ./
RUN npm install -g yarn && yarn install


# Copy application code
COPY . .


# Precompile assets for production
ENV RAILS_ENV=production
RUN bundle exec rails assets:precompile


# Create necessary directories
RUN mkdir -p /app/public/packs \
    /app/tmp/pids \
    /app/storage


# Expose port
EXPOSE 3000


# Start command
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]

Dockerfile with Custom Start Script

If you need custom initialization logic:

FROM chatwoot/chatwoot:latest


WORKDIR /app


# Copy custom startup script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh


EXPOSE 3000


ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]

docker-entrypoint.sh:

#!/bin/bash
set -e


# Run database migrations
bundle exec rails db:migrate


# Precompile assets if needed
if [ ! -f /app/tmp/.assets-compiled ]; then
  bundle exec rails assets:precompile
  touch /app/tmp/.assets-compiled
fi


# Execute the main command
exec "$@"

Deploying to Klutch.sh

Now that your repository is ready with a Dockerfile, follow these steps to deploy on Klutch.sh:

    1. Log in to Klutch.sh Dashboard

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project (if you don’t have one already)

      Click “New Project” and provide a name for your project (e.g., “Chatwoot Production”).

    3. Create a New Application

      • Click “New App” or “Create Application”
      • Select HTTP as the traffic type (Chatwoot is a web application)
      • Choose GitHub as your Git source
      • Select your Chatwoot repository from the list
      • Choose the branch you want to deploy (usually main or master)

    4. Configure Build Settings

      Klutch.sh will automatically detect your Dockerfile in the root directory. The build process will:

      • Clone your repository
      • Build the Docker image using your Dockerfile
      • Create a container from the image
      • Start your application

    5. Set Internal Port

      Configure the internal port that your application listens on:

      • Set the port to 3000 (Chatwoot’s default port)
      • Klutch.sh will automatically route HTTP traffic from port 80/443 to this internal port

    6. Configure Environment Variables (see detailed section below)

      Add all required environment variables including database credentials, secret keys, and Chatwoot-specific configuration.

    7. Deploy the Application

      Click “Create” or “Deploy” to start the deployment process. Klutch.sh will build your Docker image and start the container.

    8. Monitor Deployment

      Watch the build logs to ensure the deployment completes successfully. Once deployed, your Chatwoot instance will be accessible at https://your-app-name.klutch.sh or your configured custom domain.

Persistent Storage Configuration

Chatwoot requires persistent storage for uploaded files, attachments, avatars, and other media. Without persistent volumes, these files would be lost when the container restarts.

    1. Create a Persistent Volume

      In the Klutch.sh dashboard, navigate to your application settings and locate the “Volumes” or “Storage” section.

    2. Add Volume for Storage

      • Click “Add Volume” or “Create Volume”
      • Mount Path: /app/storage
      • Size: Start with 10GB and increase based on your usage (recommend 50GB+ for production)

      This directory will store all user uploads, file attachments, and media files.

    3. Add Volume for Public Uploads (if using separate mount)

      • Mount Path: /app/public/uploads
      • Size: 5GB or more depending on expected traffic

    4. Add Volume for Logs (optional but recommended)

      • Mount Path: /app/log
      • Size: 5GB

      This helps preserve application logs across deployments.

    5. Save Volume Configuration

      Apply the changes. Klutch.sh will mount these volumes to your container, ensuring data persists across restarts and redeployments.

Important Notes:

  • Volume data persists independently of your application container
  • Regular backups of volume data are recommended for production environments
  • Monitor volume usage and increase size as needed
  • Ensure your application has proper write permissions to mounted directories

Environment Variables Configuration

Chatwoot requires numerous environment variables for proper operation. Configure these in the Klutch.sh dashboard under your application’s environment settings.

Required Environment Variables

Database Configuration

Terminal window
# PostgreSQL Database
DATABASE_URL=postgresql://username:password@host:5432/chatwoot_production
POSTGRES_HOST=your-postgres-host
POSTGRES_PORT=5432
POSTGRES_DATABASE=chatwoot_production
POSTGRES_USERNAME=chatwoot_user
POSTGRES_PASSWORD=your-secure-password

Redis Configuration

Terminal window
REDIS_URL=redis://your-redis-host:6379
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password

Application Secrets

Terminal window
# Secret key for Rails (generate with: rails secret)
SECRET_KEY_BASE=your-generated-secret-key-minimum-128-characters


# Frontend URL (your Klutch.sh app URL)
FRONTEND_URL=https://example-app.klutch.sh


# Backend URL
BACKEND_URL=https://example-app.klutch.sh

Rails Environment

Terminal window
RAILS_ENV=production
RACK_ENV=production
NODE_ENV=production
RAILS_LOG_TO_STDOUT=true

Optional Environment Variables

Terminal window
# SMTP Settings
SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_DOMAIN=example.com
SMTP_USERNAME=your-email@example.com
SMTP_PASSWORD=your-email-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true


# Mailer configuration
MAILER_SENDER_EMAIL=support@example.com
MAILER_INBOUND_EMAIL_DOMAIN=example.com

File Storage (AWS S3 or Compatible)

Terminal window
# S3 Configuration (optional, for external storage)
ACTIVE_STORAGE_SERVICE=amazon
S3_BUCKET_NAME=your-bucket-name
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1

Additional Features

Terminal window
# Enable features
ENABLE_ACCOUNT_SIGNUP=false
ENABLE_ACCOUNT_SIGNUP=true
FORCE_SSL=true


# Chatwoot Installation Name
INSTALLATION_NAME=Chatwoot


# Default locale
DEFAULT_LOCALE=en


# Maximum file upload size (in MB)
RAILS_MAX_FILE_SIZE=40

Nixpacks Customization

If you need to customize the build or start commands using Nixpacks (Klutch.sh’s default build system), you can set these buildtime and runtime environment variables:

Custom Start Command

Terminal window
# Runtime environment variable
NIXPACKS_START_CMD=bundle exec rails server -b 0.0.0.0 -p 3000

Custom Build Command

Terminal window
# Buildtime environment variable
NIXPACKS_BUILD_CMD=bundle install && yarn install && rails assets:precompile

Custom Install Command

Terminal window
# Buildtime environment variable
NIXPACKS_INSTALL_CMD=apt-get update && apt-get install -y libpq-dev imagemagick

Note: When using a Dockerfile, Klutch.sh automatically uses Docker for building and running, so Nixpacks variables are not needed unless you’re deploying without a Dockerfile.

Database Setup

Chatwoot requires PostgreSQL as its primary database. You have two options:

Option 1: External Managed PostgreSQL

Use a managed PostgreSQL service (recommended for production):

  • AWS RDS
  • Google Cloud SQL
  • DigitalOcean Managed Databases
  • Heroku Postgres
  • Supabase

Configure the DATABASE_URL environment variable with your managed database connection string.

Option 2: Deploy PostgreSQL on Klutch.sh

You can deploy PostgreSQL as a separate application on Klutch.sh:

    1. Create a new application for PostgreSQL with TCP traffic type

    2. Use a PostgreSQL Docker image:

      FROM postgres:15-alpine
      

      ENV POSTGRES_DB=chatwoot_production
      ENV POSTGRES_USER=chatwoot_user
      # Password should be set via Klutch.sh environment variables
      

      EXPOSE 5432

    3. Configure TCP Traffic

      • Select TCP as the traffic type when creating the PostgreSQL app
      • External connections will be available on port 8000
      • Set the internal port to 5432 (PostgreSQL default)

    4. Add Persistent Volume for database data:

      • Mount Path: /var/lib/postgresql/data
      • Size: 20GB minimum (scale based on expected data)

    5. Connect from Chatwoot

      Use the internal hostname provided by Klutch.sh to connect from your Chatwoot application.

Running Database Migrations

After deploying Chatwoot, you need to run database migrations. You can do this by:

  1. Adding a migration command to your docker-entrypoint.sh script (recommended)
  2. Connecting to your container and running manually:
Terminal window
bundle exec rails db:create
bundle exec rails db:migrate
bundle exec rails db:seed

Redis Setup

Chatwoot uses Redis for caching, background jobs, and real-time features. Similar to PostgreSQL, you have options:

Option 1: External Managed Redis

Use a managed Redis service:

  • AWS ElastiCache
  • Redis Labs
  • Upstash
  • DigitalOcean Managed Redis

Option 2: Deploy Redis on Klutch.sh

    1. Create a new application for Redis with TCP traffic type

    2. Use a Redis Dockerfile:

      FROM redis:7-alpine
      

      # Optional: Add persistence configuration
      COPY redis.conf /usr/local/etc/redis/redis.conf
      

      EXPOSE 6379
      

      CMD ["redis-server", "/usr/local/etc/redis/redis.conf"]

    3. Configure TCP Traffic

      • Select TCP as the traffic type
      • External port: 8000
      • Internal port: 6379

    4. Add Persistent Volume (for data persistence):

      • Mount Path: /data
      • Size: 5GB

Getting Started with Chatwoot

Once your deployment is complete and all services are running:

    1. Access Your Chatwoot Instance

      Navigate to your application URL: https://example-app.klutch.sh

    2. Create Administrator Account

      On first access, you’ll be prompted to create an administrator account:

      • Enter your name
      • Provide email address
      • Set a secure password
      • Complete the setup wizard

    3. Configure Your First Inbox

      • Navigate to Settings → Inboxes
      • Click “Add Inbox”
      • Choose your channel type (Website, Email, API, etc.)
      • Follow the setup wizard for your selected channel

    4. Set Up Team Members

      • Go to Settings → Agents
      • Invite team members by email
      • Assign roles and permissions

    5. Customize Your Installation

      • Upload your company logo
      • Configure notification preferences
      • Set up automation rules
      • Customize widget appearance for website integration

    6. Test Conversation Flow

      • Send a test message through your configured inbox
      • Verify notifications are working
      • Test response and resolution workflow

Sample Widget Integration

To add Chatwoot to your website:

<script>
(function(d,t) {
  var BASE_URL="https://example-app.klutch.sh";
  var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
  g.src=BASE_URL+"/packs/js/sdk.js";
  g.defer = true;
  g.async = true;
  s.parentNode.insertBefore(g,s);
  g.onload=function(){
    window.chatwootSDK.run({
      websiteToken: 'YOUR_WEBSITE_TOKEN',
      baseUrl: BASE_URL
    })
  }
})(document,"script");
</script>

Replace YOUR_WEBSITE_TOKEN with the token from your Chatwoot inbox settings.

Production Best Practices

Security

  • Use HTTPS: Klutch.sh provides automatic HTTPS for your applications
  • Strong Passwords: Use complex passwords for database and Redis
  • Secret Management: Never commit secrets to your repository; use Klutch.sh environment variables
  • Disable Public Signup: Set ENABLE_ACCOUNT_SIGNUP=false in production
  • Regular Updates: Keep Chatwoot, Ruby, and dependencies updated
  • IP Restrictions: Consider restricting admin access to specific IP ranges
  • 2FA: Enable two-factor authentication for admin accounts

Performance

  • Database Connection Pooling: Configure appropriate connection pool sizes
  • Redis Memory Management: Monitor and configure Redis memory limits
  • Background Job Workers: Run separate Sidekiq worker processes for background jobs
  • Asset CDN: Consider using a CDN for static assets and uploads
  • Database Indexing: Ensure proper database indexes for frequently queried fields
  • Caching: Leverage Redis caching for frequently accessed data

Monitoring and Maintenance

  • Health Checks: Monitor application health endpoints
  • Log Management: Regularly review and rotate logs
  • Database Backups: Implement automated daily backups
  • Volume Backups: Backup persistent volumes regularly
  • Performance Metrics: Track response times, error rates, and resource usage
  • Uptime Monitoring: Use external monitoring services
  • Alert Configuration: Set up alerts for critical issues

Scaling Considerations

  • Horizontal Scaling: Add more application instances for increased traffic
  • Vertical Scaling: Increase resources (CPU, RAM) for existing instances
  • Database Scaling: Use read replicas for database scaling
  • Load Balancing: Distribute traffic across multiple instances
  • Stateless Architecture: Keep application servers stateless
  • Session Storage: Use Redis for session storage across instances
  • File Storage: Use external storage (S3) for uploads when scaling horizontally

Backup Strategy

Implement a comprehensive backup strategy:

  1. Database Backups: Daily automated PostgreSQL backups
  2. Volume Snapshots: Weekly snapshots of persistent volumes
  3. Configuration Backup: Store environment variable configurations securely
  4. Disaster Recovery Plan: Document and test recovery procedures
  5. Retention Policy: Keep backups for at least 30 days

Customization Options

Branding

Customize Chatwoot to match your brand:

  • Upload custom logo in Settings
  • Configure brand colors
  • Customize email templates
  • White-label the widget

Custom Integrations

Chatwoot supports numerous integrations:

  • Slack
  • WhatsApp Business
  • Facebook Messenger
  • Telegram
  • Email (IMAP/SMTP)
  • API webhooks for custom integrations

Automation

Set up automation rules:

  • Auto-assignment based on team availability
  • Automatic responses for common queries
  • Escalation rules for urgent issues
  • CSAT survey automation
  • SLA management

Troubleshooting

Common Issues and Solutions

Application Won’t Start

  • Check logs in Klutch.sh dashboard for error messages
  • Verify environment variables are correctly set
  • Ensure database is accessible and migrations have run
  • Check port configuration matches your Dockerfile EXPOSE statement

Database Connection Errors

  • Verify DATABASE_URL format is correct
  • Check database credentials are accurate
  • Ensure database is running and accessible
  • Test connection from your application container
  • Check network connectivity between services

File Upload Issues

  • Verify persistent volume is mounted correctly
  • Check mount path matches Chatwoot’s storage configuration
  • Ensure sufficient disk space in volume
  • Verify file permissions on mounted directories
  • Check RAILS_MAX_FILE_SIZE environment variable

Redis Connection Problems

  • Verify REDIS_URL is correctly formatted
  • Check Redis service is running
  • Test connectivity from application container
  • Verify Redis password if authentication is enabled

Performance Issues

  • Monitor resource usage (CPU, RAM, disk I/O)
  • Check database performance and query optimization
  • Review Sidekiq worker performance and queue sizes
  • Analyze slow logs to identify bottlenecks
  • Consider scaling resources or adding instances

Email Delivery Issues

  • Verify SMTP settings are correct
  • Check email provider allows SMTP connections
  • Test email credentials independently
  • Review email logs for delivery errors
  • Check spam filters and email reputation

Monitoring and Observability

Application Logs

Access logs through:

  • Klutch.sh dashboard log viewer
  • Mounted log volume at /app/log
  • STDOUT/STDERR (with RAILS_LOG_TO_STDOUT=true)

Key Metrics to Monitor

  • Response Time: Monitor API and page load times
  • Error Rate: Track 4xx and 5xx errors
  • Throughput: Messages processed per minute
  • Database Performance: Query time and connection pool usage
  • Background Jobs: Sidekiq queue depth and processing time
  • Memory Usage: Application and database memory consumption
  • Disk Usage: Volume capacity and I/O operations
  • Application Performance: New Relic, Datadog, Scout APM
  • Error Tracking: Sentry, Rollbar
  • Uptime Monitoring: UptimeRobot, Pingdom
  • Log Aggregation: Papertrail, Loggly
  • Infrastructure: Klutch.sh built-in metrics

Upgrading Chatwoot

To upgrade to a newer version of Chatwoot:

    1. Review Release Notes

      Check the Chatwoot releases page for breaking changes and migration notes.

    2. Update Dockerfile

      Change the version tag in your Dockerfile:

      FROM chatwoot/chatwoot:v3.0.0

    3. Backup Everything

      • Create database backup
      • Snapshot persistent volumes
      • Export configuration

    4. Deploy Updated Version

      Commit and push your Dockerfile changes. Klutch.sh will automatically rebuild and redeploy.

    5. Run Migrations

      If your entrypoint script includes migrations, they’ll run automatically. Otherwise, run manually:

      Terminal window
      bundle exec rails db:migrate

    6. Verify Functionality

      • Test all critical features
      • Check integrations are working
      • Verify data integrity
      • Monitor logs for errors

Cost Optimization

Tips for Reducing Costs

  1. Right-Size Resources: Start small and scale based on actual usage
  2. Volume Management: Regularly clean up old attachments and logs
  3. Database Optimization: Archive old conversations to reduce database size
  4. Efficient Caching: Proper Redis configuration reduces database load
  5. Image Optimization: Compress and optimize uploaded images
  6. CDN Usage: Serve static assets from a CDN to reduce bandwidth costs

Additional Resources

Official Documentation

Klutch.sh Documentation

Community Resources

Conclusion

Deploying Chatwoot on Klutch.sh provides a powerful, scalable solution for customer engagement and support. With automatic Dockerfile detection, persistent storage, and easy environment configuration, you can have a production-ready Chatwoot instance running quickly. The platform handles infrastructure complexities, allowing you to focus on delivering exceptional customer experiences.

By following this guide, you’ve learned how to:

  • Set up a Chatwoot deployment with a Dockerfile
  • Configure persistent storage for uploads and data
  • Manage environment variables and secrets
  • Set up PostgreSQL and Redis services
  • Implement production best practices
  • Monitor and maintain your deployment

For advanced configurations, custom integrations, or scaling needs, refer to the official Chatwoot documentation and Klutch.sh support resources. Happy deploying!