First Commit
This commit is contained in:
edwin
282
CHATWOOT_SETUP_GUIDE.md
Normal file
282
CHATWOOT_SETUP_GUIDE.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# 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
|
||||
```bash
|
||||
wget https://example.com/chatwoot_install.sh
|
||||
chmod +x chatwoot_install.sh
|
||||
```
|
||||
|
||||
Or clone from GitHub:
|
||||
```bash
|
||||
git clone https://github.com/chatwoot/chatwoot.git
|
||||
cd chatwoot/deployment
|
||||
sudo bash setup_20.04.sh
|
||||
```
|
||||
|
||||
### 2. Run the Installation Script
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
sudo certbot certonly --nginx -d yourdomain.com
|
||||
```
|
||||
|
||||
Then restart Nginx:
|
||||
```bash
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
## Post-Installation Setup
|
||||
|
||||
### 1. Edit Environment Variables
|
||||
The `.env` file controls Chatwoot configuration. Update it with your specific settings:
|
||||
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
cd /home/chatwoot/chatwoot
|
||||
bundle exec rake db:migrate RAILS_ENV=production
|
||||
```
|
||||
|
||||
### 3. Create Admin User
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
systemctl status chatwoot-web.target
|
||||
systemctl status chatwoot-worker.target
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
systemctl restart chatwoot-web.target
|
||||
systemctl restart chatwoot-worker.target
|
||||
```
|
||||
|
||||
### Stop Services
|
||||
```bash
|
||||
systemctl stop chatwoot-web.target
|
||||
systemctl stop chatwoot-worker.target
|
||||
```
|
||||
|
||||
## Upgrading Chatwoot
|
||||
|
||||
### Using cwctl (Recommended)
|
||||
```bash
|
||||
cwctl --upgrade
|
||||
```
|
||||
|
||||
### Manual Upgrade
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
sudo -u postgres pg_dump -Fc chatwoot_production > chatwoot_backup.sql
|
||||
```
|
||||
|
||||
### Restore Database
|
||||
```bash
|
||||
sudo -u postgres pg_restore -d chatwoot_production chatwoot_backup.sql
|
||||
```
|
||||
|
||||
### Backup Application Files
|
||||
```bash
|
||||
tar -czf chatwoot_app_backup.tar.gz /home/chatwoot/chatwoot
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Won't Start
|
||||
Check logs for errors:
|
||||
```bash
|
||||
journalctl -u chatwoot-web.1.service -n 50
|
||||
```
|
||||
|
||||
### Asset Compilation Issues
|
||||
Clear compiled assets and recompile:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
systemctl status postgresql
|
||||
```
|
||||
|
||||
Check database credentials in `.env` file match PostgreSQL configuration.
|
||||
|
||||
### Out of Memory During Installation
|
||||
Increase swap space:
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user