monoadmin/Chatwoot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Chatwoot/CHATWOOT_CONFIG_TROUBLESHOOTING.md
edwin 53e7089382 First Commit
2026-02-04 01:42:45 -08:00

10 KiB
Raw Permalink Blame History

Chatwoot Configuration & Troubleshooting Guide

Common Environment Variables (.env)

Edit with: sudo nano /home/chatwoot/chatwoot/.env

Core Configuration

RAILS_ENV=production                          # Always use production for live
SECRET_KEY_BASE=your-secret-key               # Generated during install
FRONTEND_URL=https://yourdomain.com          # Where Chatwoot is accessed from

Database Configuration

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USERNAME=chatwoot
POSTGRES_PASSWORD=your_secure_password        # IMPORTANT: Change this!
POSTGRES_DATABASE=chatwoot_production

Redis Configuration

REDIS_URL=redis://localhost:6379/0

Account Signup

ENABLE_ACCOUNT_SIGNUP=false                  # true to allow new signups

Email Configuration (Choose One)

SMTP:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true

Mailgun:

MAILGUN_SMTP_ENABLED=true
MAILGUN_SMTP_DOMAIN=your-domain.mailgun.org
MAILGUN_SMTP_LOGIN=postmaster@your-domain.mailgun.org
MAILGUN_SMTP_PASSWORD=your-mailgun-key

Integrations

Facebook:

FACEBOOK_CHANNEL_ENABLED=true
FACEBOOK_APP_ID=your-app-id
FACEBOOK_APP_SECRET=your-app-secret

WhatsApp:

WHATSAPP_CHANNEL_ENABLED=true
WHATSAPP_API_KEY=your-api-key

Google Analytics:

GOOGLE_ANALYTICS_ID=UA-XXXXXXXX-X

Security

ENABLE_ACCOUNT_SIGNUP=false
CORS_ORIGINS=https://yourdomain.com

Nginx Configuration Examples

Basic HTTP (Port 3000)

server {
    listen 80;
    server_name _;
    
    location / {
        proxy_pass http://127.0.0.1:3000;
        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;
        underscores_in_headers on;
    }
}

HTTPS with Let's Encrypt

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

# HTTPS Server
server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    
    location / {
        proxy_pass http://127.0.0.1:3000;
        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 https;
        proxy_buffering off;
        underscores_in_headers on;
    }
}

Troubleshooting Guide

Issue: Chatwoot Won't Start

Check Service Status:

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

View Detailed Logs:

journalctl -u chatwoot-web.1.service -n 100
journalctl -u chatwoot-worker.1.service -n 100

Common Causes:

  1. Database connection error - verify PostgreSQL is running
  2. Redis unavailable - check Redis service
  3. Asset compilation failed - recompile assets
  4. Port already in use - check port 3000

Solutions:

# Restart PostgreSQL
sudo systemctl restart postgresql

# Restart Redis
sudo systemctl restart redis-server

# Recompile assets
cd /home/chatwoot/chatwoot
bundle exec rake assets:precompile RAILS_ENV=production NODE_OPTIONS="--max-old-space-size=4096 --openssl-legacy-provider"

# Clear Rails cache
cd /home/chatwoot/chatwoot
bundle exec rake cache:clear RAILS_ENV=production

Issue: High Memory Usage

Check Memory:

free -h
top -b -n 1 | head -20

Solutions:

  1. Increase swap space:
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
  1. Optimize Sidekiq workers in .env:
SIDEKIQ_CONCURRENCY=5
SIDEKIQ_MEMORY_KILLER_MAX_SIZE=800
  1. Reduce Rails threads:
WEB_CONCURRENCY=2
MAX_THREADS=4

Issue: Slow Performance

Check System Resources:

# CPU usage
top
# Disk I/O
iostat -x 1 5
# Network connections
netstat -an | grep ESTABLISHED

Optimization Steps:

  1. Database Optimization:
# Connect to PostgreSQL
sudo -u postgres psql chatwoot_production

# Analyze database
ANALYZE;
  1. Redis Optimization:
# Check Redis memory
redis-cli info memory
# Clear Redis cache
redis-cli flushall
  1. Nginx Optimization:
# Add to http block in nginx.conf
client_max_body_size 20M;
gzip on;
gzip_types text/plain text/css text/javascript application/json application/javascript;
  1. Scale Sidekiq Workers: Edit /etc/systemd/system/chatwoot-worker.1.service:
Environment="SIDEKIQ_CONCURRENCY=10"
ExecStart=/bin/bash -lc 'exec bundle exec sidekiq -c 10 -e $RAILS_ENV'

Issue: SSL Certificate Not Renewing

Check Certificate Expiry:

sudo certbot certificates

Manual Renewal:

sudo certbot renew --nginx

Auto-Renewal Check:

sudo systemctl status certbot.timer
sudo systemctl enable certbot.timer

Issue: Database Corruption

Check Database Health:

sudo -u postgres psql chatwoot_production -c "PRAGMA integrity_check;"

Restore from Backup:

sudo -u postgres dropdb chatwoot_production
sudo -u postgres createdb chatwoot_production -O chatwoot
sudo -u postgres pg_restore -d chatwoot_production /path/to/backup.sql

Issue: Email Not Sending

Check SMTP Configuration:

cd /home/chatwoot/chatwoot
sudo -u chatwoot bundle exec rails console production

Test Email:

ActionMailer::Base.mail(
  from: 'test@example.com',
  to: 'admin@example.com',
  subject: 'Test Email',
  body: 'This is a test email'
).deliver_now

Issue: Agents Can't Login

Check Agent Access:

cd /home/chatwoot/chatwoot
sudo -u chatwoot bundle exec rails console production

# Check user
User.find_by(email: 'agent@example.com')

# Reset password
user = User.find_by(email: 'agent@example.com')
user.update(password: 'newpassword123')

Issue: Database Migrations Failed

Run Migrations Manually:

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

Rollback Migration:

cd /home/chatwoot/chatwoot
sudo -u chatwoot bundle exec rake db:rollback STEP=1 RAILS_ENV=production

Maintenance Tasks

Regular Backups

#!/bin/bash
# Daily backup script

BACKUP_DIR="/backups/chatwoot"
DATE=$(date +%Y-%m-%d)

mkdir -p $BACKUP_DIR

# Database backup
sudo -u postgres pg_dump -Fc chatwoot_production > $BACKUP_DIR/db_$DATE.sql

# Application backup
tar -czf $BACKUP_DIR/app_$DATE.tar.gz \
    -C /home/chatwoot chatwoot \
    --exclude='*.log' \
    --exclude='tmp/*' \
    --exclude='public/packs/*'

# Keep only last 30 days
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete

Monitor Disk Space

# Check disk usage
df -h

# Find large files
du -sh /home/chatwoot/chatwoot/*

# Clean logs
journalctl --vacuum-time=30d
rm -f /var/log/chatwoot/*.log.*

Monitor Services

#!/bin/bash
# Service monitoring script

# Check services
systemctl is-active chatwoot-web.target || systemctl restart chatwoot-web.target
systemctl is-active chatwoot-worker.target || systemctl restart chatwoot-worker.target
systemctl is-active postgresql || systemctl restart postgresql
systemctl is-active redis-server || systemctl restart redis-server
systemctl is-active nginx || systemctl restart nginx

Update Chatwoot

cd /home/chatwoot/chatwoot

# If cwctl is available
cwctl --upgrade

# Or manual update
git fetch origin
git checkout v3.x.x  # Replace with version
bundle install
bundle exec rake db:migrate RAILS_ENV=production
bundle exec rake assets:precompile RAILS_ENV=production NODE_OPTIONS="--max-old-space-size=4096 --openssl-legacy-provider"
systemctl restart chatwoot-web.target chatwoot-worker.target

Performance Monitoring

Check Active Connections

# Database connections
sudo -u postgres psql -c "SELECT count(*) FROM pg_stat_activity;"

# Redis connections
redis-cli CLIENT LIST

Monitor CPU and Memory

# Real-time monitoring
watch -n 1 'top -b -n 1 | head -20'

# Systemd resource limits
systemctl status chatwoot-web.target --full

Security Hardening

UFW Firewall Setup

sudo ufw enable
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw default deny incoming
sudo ufw default allow outgoing

Nginx Security Headers

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

SSH Hardening

# Edit /etc/ssh/sshd_config
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
X11Forwarding no

# Restart SSH
sudo systemctl restart ssh

Useful Commands Quick Reference

# View real-time logs
journalctl -f -u chatwoot-web.1.service

# Restart all services
systemctl restart chatwoot-web.target chatwoot-worker.target

# Access Rails console
cd /home/chatwoot/chatwoot && sudo -u chatwoot bundle exec rails console production

# Check Chatwoot version
cd /home/chatwoot/chatwoot && git describe --tags

# Database status
sudo -u postgres psql -d chatwoot_production -c "\dt"

# Redis info
redis-cli INFO

# Check port usage
sudo netstat -tlnp | grep 3000
Reference in New Issue View Git Blame Copy Permalink