481 lines
10 KiB
Markdown
481 lines
10 KiB
Markdown
# 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)
|
|
```nginx
|
|
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
|
|
```nginx
|
|
# 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:**
|
|
```bash
|
|
systemctl status chatwoot-web.target
|
|
systemctl status chatwoot-worker.target
|
|
```
|
|
|
|
**View Detailed Logs:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
free -h
|
|
top -b -n 1 | head -20
|
|
```
|
|
|
|
**Solutions:**
|
|
1. Increase swap space:
|
|
```bash
|
|
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
|
|
```
|
|
|
|
2. Optimize Sidekiq workers in `.env`:
|
|
```
|
|
SIDEKIQ_CONCURRENCY=5
|
|
SIDEKIQ_MEMORY_KILLER_MAX_SIZE=800
|
|
```
|
|
|
|
3. Reduce Rails threads:
|
|
```
|
|
WEB_CONCURRENCY=2
|
|
MAX_THREADS=4
|
|
```
|
|
|
|
### Issue: Slow Performance
|
|
|
|
**Check System Resources:**
|
|
```bash
|
|
# CPU usage
|
|
top
|
|
# Disk I/O
|
|
iostat -x 1 5
|
|
# Network connections
|
|
netstat -an | grep ESTABLISHED
|
|
```
|
|
|
|
**Optimization Steps:**
|
|
|
|
1. **Database Optimization:**
|
|
```bash
|
|
# Connect to PostgreSQL
|
|
sudo -u postgres psql chatwoot_production
|
|
|
|
# Analyze database
|
|
ANALYZE;
|
|
```
|
|
|
|
2. **Redis Optimization:**
|
|
```bash
|
|
# Check Redis memory
|
|
redis-cli info memory
|
|
# Clear Redis cache
|
|
redis-cli flushall
|
|
```
|
|
|
|
3. **Nginx Optimization:**
|
|
```nginx
|
|
# 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;
|
|
```
|
|
|
|
4. **Scale Sidekiq Workers:**
|
|
Edit `/etc/systemd/system/chatwoot-worker.1.service`:
|
|
```ini
|
|
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:**
|
|
```bash
|
|
sudo certbot certificates
|
|
```
|
|
|
|
**Manual Renewal:**
|
|
```bash
|
|
sudo certbot renew --nginx
|
|
```
|
|
|
|
**Auto-Renewal Check:**
|
|
```bash
|
|
sudo systemctl status certbot.timer
|
|
sudo systemctl enable certbot.timer
|
|
```
|
|
|
|
### Issue: Database Corruption
|
|
|
|
**Check Database Health:**
|
|
```bash
|
|
sudo -u postgres psql chatwoot_production -c "PRAGMA integrity_check;"
|
|
```
|
|
|
|
**Restore from Backup:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
cd /home/chatwoot/chatwoot
|
|
sudo -u chatwoot bundle exec rails console production
|
|
```
|
|
|
|
**Test Email:**
|
|
```ruby
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
cd /home/chatwoot/chatwoot
|
|
sudo -u chatwoot bundle exec rake db:migrate RAILS_ENV=production
|
|
```
|
|
|
|
**Rollback Migration:**
|
|
```bash
|
|
cd /home/chatwoot/chatwoot
|
|
sudo -u chatwoot bundle exec rake db:rollback STEP=1 RAILS_ENV=production
|
|
```
|
|
|
|
## Maintenance Tasks
|
|
|
|
### Regular Backups
|
|
```bash
|
|
#!/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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
#!/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
|
|
```bash
|
|
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
|
|
```bash
|
|
# Database connections
|
|
sudo -u postgres psql -c "SELECT count(*) FROM pg_stat_activity;"
|
|
|
|
# Redis connections
|
|
redis-cli CLIENT LIST
|
|
```
|
|
|
|
### Monitor CPU and Memory
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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
|
|
```nginx
|
|
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
|
|
```bash
|
|
# Edit /etc/ssh/sshd_config
|
|
PermitRootLogin no
|
|
PasswordAuthentication no
|
|
PubkeyAuthentication yes
|
|
X11Forwarding no
|
|
|
|
# Restart SSH
|
|
sudo systemctl restart ssh
|
|
```
|
|
|
|
## Useful Commands Quick Reference
|
|
|
|
```bash
|
|
# 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
|
|
```
|