283 lines
6.7 KiB
Markdown
283 lines
6.7 KiB
Markdown
# 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
|