Chatwoot/CHATWOOT_SETUP_GUIDE.md

Chatwoot Installation Guide for Ubuntu

Overview

This guide covers installing Chatwoot (an open-source customer engagement platform) on Ubuntu 20.04, 22.04, or 24.04 LTS using an automated installation script.

Prerequisites

System Requirements:

• Ubuntu 20.04 LTS, 22.04 LTS, or 24.04 LTS
• Minimum 4 cores (8 cores recommended for production)
• Minimum 4GB RAM (8GB or more for production)
• At least 20GB free disk space
• Root or sudo access
• (Optional) A domain name for SSL configuration

Open Required Ports:

• Port 80 (HTTP)
• Port 443 (HTTPS, if using SSL)
• Port 3000 (if accessing directly without reverse proxy)

Quick Start

1. Download the Installation Script

wget https://example.com/chatwoot_install.sh
chmod +x chatwoot_install.sh

Or clone from GitHub:

git clone https://github.com/chatwoot/chatwoot.git
cd chatwoot/deployment
sudo bash setup_20.04.sh

2. Run the Installation Script

sudo bash chatwoot_install.sh

This will:

• Update system packages
• Install all dependencies (Ruby, Node.js, PostgreSQL, Redis, Nginx)
• Create the chatwoot user
• Clone the Chatwoot repository
• Setup PostgreSQL database
• Install Ruby gems
• Compile assets
• Configure systemd services
• Setup Nginx as a reverse proxy
• Start all services

The installation typically takes 30-60 minutes.

3. Access Chatwoot

After installation completes, access Chatwoot at:

http://your-server-ip:3000

Configuration with Domain and SSL

Using the Installation Script

If you have a domain name and an A record pointing to your server:

sudo bash chatwoot_install.sh --ssl --domain yourdomain.com --email admin@yourdomain.com

This will:

• Configure Nginx for your domain
• Generate SSL certificates using Let's Encrypt
• Enable automatic HTTPS
• Access Chatwoot at https://yourdomain.com

Manual SSL Configuration

If you prefer manual setup:

sudo certbot certonly --nginx -d yourdomain.com

Then restart Nginx:

sudo systemctl restart nginx

Post-Installation Setup

1. Edit Environment Variables

The .env file controls Chatwoot configuration. Update it with your specific settings:

sudo nano /home/chatwoot/chatwoot/.env

Key variables:

• RAILS_ENV=production - Environment mode
• POSTGRES_HOST=localhost - Database host
• POSTGRES_USERNAME=chatwoot - Database user
• POSTGRES_PASSWORD= - Database password (change this!)
• REDIS_URL=redis://localhost:6379 - Redis connection
• ENABLE_ACCOUNT_SIGNUP=true/false - Allow new user registration
• MAILGUN_SMTP_ENABLED=true/false - Email configuration
• FACEBOOK_CHANNEL_ENABLED=true/false - Channel integrations

2. Run Database Migrations

cd /home/chatwoot/chatwoot
bundle exec rake db:migrate RAILS_ENV=production

3. Create Admin User

cd /home/chatwoot/chatwoot
bundle exec rake chatwoot:create_account[account_name]
bundle exec rake chatwoot:create_user[email@example.com,admin_name,Admin,password]

Alternatively, use the web interface to create the first admin user after accessing Chatwoot.

4. Configure Integrations

Log in to the Chatwoot dashboard and configure:

• Email accounts
• Social media channels (Facebook, WhatsApp, Instagram)
• Live chat widget
• Custom API keys

Service Management

Check Service Status

systemctl status chatwoot-web.target
systemctl status chatwoot-worker.target

View Logs

# Web service logs
journalctl -u chatwoot-web.1.service -f

# Worker service logs
journalctl -u chatwoot-worker.1.service -f

# Installation logs
tail -f /var/log/chatwoot-setup.log

Restart Services

systemctl restart chatwoot-web.target
systemctl restart chatwoot-worker.target

Stop Services

systemctl stop chatwoot-web.target
systemctl stop chatwoot-worker.target

Upgrading Chatwoot

Using cwctl (Recommended)

cwctl --upgrade

Manual Upgrade

cd /home/chatwoot/chatwoot
git fetch origin
git checkout v3.x.x  # Replace with desired version
bundle install
rake db:migrate RAILS_ENV=production
rake assets:precompile RAILS_ENV=production
systemctl restart chatwoot-web.target chatwoot-worker.target

Backup and Restore

Create Database Backup

sudo -u postgres pg_dump -Fc chatwoot_production > chatwoot_backup.sql

Restore Database

sudo -u postgres pg_restore -d chatwoot_production chatwoot_backup.sql

Backup Application Files

tar -czf chatwoot_app_backup.tar.gz /home/chatwoot/chatwoot

Troubleshooting

Service Won't Start

Check logs for errors:

journalctl -u chatwoot-web.1.service -n 50

Asset Compilation Issues

Clear compiled assets and recompile:

cd /home/chatwoot/chatwoot
rm -rf public/packs/*
bundle exec rake assets:precompile RAILS_ENV=production NODE_OPTIONS="--max-old-space-size=4096 --openssl-legacy-provider"

Database Connection Issues

Verify PostgreSQL is running:

systemctl status postgresql

Check database credentials in .env file match PostgreSQL configuration.

Out of Memory During Installation

Increase swap space:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Security Recommendations

1. Change Default Passwords

   • Update PostgreSQL password
   • Update Redis password
   • Create strong admin credentials

2. Enable SSL/HTTPS

   • Always use HTTPS in production
   • Use valid SSL certificates
   • Implement HTTP to HTTPS redirects

3. Configure Firewall

   sudo ufw enable
   sudo ufw allow 22/tcp
   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   

4. Regular Updates

   • Keep Ubuntu packages updated: sudo apt update && sudo apt upgrade
   • Keep Chatwoot updated to latest stable version
   • Monitor security advisories

5. Database Security

   • Use strong PostgreSQL passwords
   • Restrict database access to localhost
   • Regular backups with secure storage

Additional Resources

• Official Documentation: https://www.chatwoot.com/docs/self-hosted
• Community Forum: https://www.chatwoot.com/community
• GitHub Repository: https://github.com/chatwoot/chatwoot
• API Documentation: https://docs.chatwoot.com/api/inbox

Getting Help

If you encounter issues:

1. Check the installation logs: /var/log/chatwoot-setup.log
2. Review service logs: journalctl -u chatwoot-* -f
3. Visit the Chatwoot community forum
4. Check GitHub issues: https://github.com/chatwoot/chatwoot/issues
5. Consult the official documentation

Support the Project

Chatwoot is open-source and maintained by the community. Consider:

• Starring the GitHub repository
• Contributing code or translations
• Supporting the project financially
• Reporting issues and bugs