# 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
```