First Commit
This commit is contained in:
edwin
480
CHATWOOT_CONFIG_TROUBLESHOOTING.md
Normal file
480
CHATWOOT_CONFIG_TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,480 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user