# 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