akadmin/chatwoot
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

add intro documentation and user guide

Browse Source
This commit is contained in:
Tanmay Deep Sharma
2025-05-29 19:29:32 +05:30
parent f429db89b4
commit 7808634432
203 changed files with 8020 additions and 7794 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-docs/self-hosted/cloud/aws.mdx
+190 -414
View File
@@ -1,501 +1,277 @@
---
title: AWS Deployment
description: Deploy Chatwoot on Amazon Web Services with manual installation or marketplace AMI
sidebarTitle: AWS
title: AWS Chatwoot deployment guide
description: Deploy Chatwoot on AWS with a reference HA architecture
sidebarTitle: Manual Install
---
# AWS Deployment Guide
The following is a reference HA architecture guide for deploying Chatwoot on AWS. For a cloud-native deployment, use our [helm charts](https://github.com/chatwoot/charts) with AWS Elastic Kubernetes Service(EKS).
Deploy Chatwoot on Amazon Web Services (AWS) using either manual installation or the AWS Marketplace AMI for a scalable, production-ready setup.
## Introduction
## Deployment Options
<CardGroup cols={2}>
<Card title="Manual Installation" icon="code" href="#manual-installation">
Full control over the deployment with custom architecture
</Card>
<Card title="AWS Marketplace AMI" icon="aws" href="#aws-marketplace-ami">
Quick deployment using pre-configured AMI
</Card>
</CardGroup>
## Manual Installation
### Architecture Overview
This guide follows a standard 3-tier architecture on AWS for high availability:
```
Internet Gateway
|
Application Load Balancer (Public Subnets)
|
Chatwoot Instances (Private Subnets)
|
RDS PostgreSQL + ElastiCache Redis (Private Subnets)
```
We will use the Linux installation script to get a chatwoot instance running. Also instead of
relying on Redis, Postgres and Nginx installed in the same ec2; we will proceed to make use
of managed AWS services for the same viz Elasticache, RDS, and ALB.
### Prerequisites
- AWS account with appropriate permissions
- Domain name for your Chatwoot installation
- Basic knowledge of AWS services (VPC, EC2, RDS, etc.)
1. AWS account
2. Domain to use with Chatwoot
### Step 1: Network Setup
### Architecture
#### Create VPC
This guide will follow a standard 3-tier architecture on AWS.
1. Navigate to the VPC console in your chosen AWS region
2. Create a new VPC:
- **Name**: `chatwoot-vpc`
- **CIDR block**: `10.0.0.0/16`
- Leave other options as default
![aws-architecture](/self-hosted/images/aws-01-architecture.png)
#### Create Subnets
## Network
Create subnets across two availability zones:
### Create VPC
| Name | Type | AZ | CIDR Block |
|------|------|----|-----------|
| chatwoot-public-1 | Public | us-east-1a | 10.0.0.0/24 |
| chatwoot-public-2 | Public | us-east-1b | 10.0.1.0/24 |
| chatwoot-private-1 | Private | us-east-1a | 10.0.2.0/24 |
| chatwoot-private-2 | Private | us-east-1b | 10.0.3.0/24 |
1. Sign in to the AWS console and pick the region you will deploy.
2. Navigate to the VPC console and create a new vpc for chatwoot. At the `name` tag, enter
`chatwoot-vpc` and use the CIDR block `10.0.0.0/16`.
3. Leave the rest of the options as default and click on `Create VPC`.
<Note>
Enable "Auto-assign public IPv4 address" for public subnets under Actions > Subnet Settings.
</Note>
![aws-create-vpc](/self-hosted/images/aws-02-create-vpc.png)
#### Internet Gateway
### Subnets
Create two public and private subnets in the vpc we created. Make sure to have them in different AZ's and have non-overlapping CIDR ranges.
1. Create Internet Gateway named `chatwoot-igw`
2. Attach it to `chatwoot-vpc`
1. Navigate to VPC > Subnets.
2. Click on `Create Subnet`. Select the `chatwoot-vpc` we created before, name it as `chatwoot-public-1`, select an availability zone (for example, ap-south-1a), and the CIDR block as
`10.0.0.0/24`.
#### NAT Gateways
![aws-create-subnet](/self-hosted/images/aws-03-create-subnet.png)
Create NAT gateways in each public subnet:
3. Follow the same to create the remaining subnets.
1. **chatwoot-nat-1** in `chatwoot-public-1`
2. **chatwoot-nat-2** in `chatwoot-public-2`
| Name | Type | Availability Zone | CIDR Block |
| ------------------- | -------- | ------------------ | ------------- |
| `chatwoot-public-1` | public | `ap-south-1a` | `10.0.0.0/24` |
| `chatwoot-public-2` | public | `ap-south-1b` | `10.0.1.0/24` |
| `chatwoot-private-1` | private | `ap-south-1a` | `10.0.2.0/24` |
| `chatwoot-private-2` | private | `ap-south-1b` | `10.0.3.0/24` |
Allocate Elastic IPs for each NAT gateway.
4. After creating all subnets, enable `auto assign public ipv4 address` for public subnets under `Actions` > `Subnet Settings`.
#### Route Tables
### Internet Gateway
**Public Route Table** (`chatwoot-public-rt`):
- Route: `0.0.0.0/0` → `chatwoot-igw`
- Associate with public subnets
1. Select `Create Internet Gateway` , name it `chatwoot-igw`, and click create.
2. Select it from the internet gateways list, choose actions and then select `Attach to VPC`.
3. Choose `chatwoot-vpc` and click attach.
**Private Route Tables**:
- `chatwoot-private-a`: Route `0.0.0.0/0` → `chatwoot-nat-1`
- `chatwoot-private-b`: Route `0.0.0.0/0` → `chatwoot-nat-2`
![aws-create-igw](/self-hosted/images/aws-04-create-igw.png)
### Step 2: Application Load Balancer
### NAT Gateway
1. Navigate to EC2 > Load Balancers
2. Create Application Load Balancer:
- **Name**: `chatwoot-loadbalancer`
- **Scheme**: Internet-facing
- **IP address type**: IPv4
- **VPC**: `chatwoot-vpc`
- **Subnets**: Select both public subnets
Chatwoot app servers need to be deployed in the private subnet. For them to access the internet, we need to add NAT gateways to our public subnet and add a route from the private subnets.
#### Security Group for ALB
1. Navigate the VPC dashboard and select `NAT gateways`.
2. Click `Create NAT Gateway`.
Create `chatwoot-loadbalancer-sg` with rules:
- HTTP (80) from `0.0.0.0/0`
- HTTPS (443) from `0.0.0.0/0`
- TCP (3000) from `0.0.0.0/0` (for health checks)
1. Name it `chatwoot-nat-1`.
2. Select the `chatwoot-public-1` subnet.
3. Click on `Allocate Elastic IP`.
4. Add additional tags as per your need.
5. Click `Create NAT gateway`.
#### Target Group
![aws-create-nat](/self-hosted/images/aws-05-create-nat.png)
Create `chatwoot-tg` target group:
- **Target type**: Instances
- **Protocol**: HTTP
- **Port**: 3000
- **Health check path**: `/api`
3. Follow the same to create a second NAT gateway (`chatwoot-nat-2`) and choose the `chatwoot-public-2` subnet.
### Step 3: Database Setup (RDS)
### Route tables
#### RDS Security Group
The route table controls the inbound and outbound access for a subnet.
Create `chatwoot-rds-sg`:
- PostgreSQL (5432) from `chatwoot-loadbalancer-sg`
#### Public Route table
#### RDS Subnet Group
We will create route tables so that our public subnets can reach the internet via the Internet gateway.
Create `chatwoot-rds-group`:
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets
Navigate to the VPC dashboard and select `Route Tables`.
1. Click `Create route table`.
2. Use the name `chatwoot-public-rt` and choose `chatwoot-vpc` under VPC.
3. Click `Create`.
#### Create RDS Instance
![aws-create-rt](/self-hosted/images/aws-06-create-rt.png)
1. Navigate to RDS > Databases
2. Create database:
- **Engine**: PostgreSQL
- **Template**: Production
- **DB instance identifier**: `chatwoot-db`
- **Master username**: `chatwoot`
- **Master password**: Generate secure password
- **DB instance class**: `db.t3.medium` (minimum)
- **Storage**: 100 GB GP2 (minimum)
- **Multi-AZ**: Yes
- **VPC**: `chatwoot-vpc`
- **Subnet group**: `chatwoot-rds-group`
- **Security group**: `chatwoot-rds-sg`
Next, we need to add a route to the internet gateway we created earlier(`chatwoot-igw`).
<Warning>
Note down the RDS endpoint, username, and password for later configuration.
</Warning>
1. Select the `chatwoot-public-rt` route table from the list and click on `Edit routes` > `Add Route`.
2. Set the destination as `0.0.0.0/0` and choose the target as `chatwoot-igw`. Click on `Save Changes`.
### Step 4: Redis Setup (ElastiCache)
Also,
#### ElastiCache Security Group
1. Select the `chatwoot-public-rt` route table from the list and click on `Subnet Associations` > `Edit subnet associations`.
2. Select both the public subnets(`chatwoot-public-1`,`chatwoot-public-2`) and click `save`.
Create `chatwoot-redis-sg`:
- Redis (6379) from `chatwoot-loadbalancer-sg`
#### Private Route table
#### ElastiCache Subnet Group
We will also create private route tables so that our private subnets can reach the internet via the NAT gateways.
Create `chatwoot-redis-group`:
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets
1. Follow the above guide and create two private route tables, namely, `chatwoot-private-a` and `chatwoot-private-b`.
2. Select the route tables and add a route to the NAT gateway in their respective availability zone.
1. For `chatwoot-private-a`, add a route to `0.0.0.0/0` and target as `chatwoot-nat-1`.
2. For `chatwoot-private-b`, add a route to `0.0.0.0/0` and target as `chatwoot-nat-2`.
#### Create Redis Cluster
Also,
1. Navigate to ElastiCache > Redis clusters
2. Create cluster:
- **Name**: `chatwoot-redis`
- **Engine version**: 7.0+
- **Node type**: `cache.t3.micro` (minimum)
- **Multi-AZ**: Yes
- **Subnet group**: `chatwoot-redis-group`
- **Security group**: `chatwoot-redis-sg`
1. Associate the private route tables with corresponding private subnets.
1. For `chatwoot-private-a`, associate `chatwoot-private-1` subnet.
2. For `chatwoot-private-b`, associate `chatwoot-private-2` subnet.
### Step 5: Bastion Host
## Application Load Balancer (ALB)
Create bastion servers for secure access to private instances:
Create an application load balancer to receive traffic on port 80 and 443 and distribute it across Chatwoot instances.
1. Launch EC2 instance:
- **AMI**: Ubuntu 20.04 LTS
- **Instance type**: `t3.micro`
- **VPC**: `chatwoot-vpc`
- **Subnet**: `chatwoot-public-1`
- **Auto-assign public IP**: Yes
- **Security group**: Create `chatwoot-bastion-sg` (SSH from your IP)
1. Navigate to the EC2 section and choose the Load Balancer section.
2. Click `Create Load Balancer`.
1. Choose `Application Load Balancer`.
2. For the load balancer name, use `chatwoot-loadbalancer`.
3. Select the scheme as `internet-facing` and IP address type as `IPv4`.
4. For the network mapping section,
1. Select `chatwoot-vpc`.
2. Select the public subnets `chatwoot-public-1` and `chatwoot-public-2` under the mapping section.
5. For the Security group section,
1. Create a new security group, `chatwoot-loadbalancer-sg`.
2. Add rules to allow HTTP and HTTPS traffic from anywhere(`0.0.0.0/0`, `::/0`).
3. Also, add a rule to allow TCP on port 3000. This rule allows the load balancer health checks to pass since Chatwoot runs on port 3000.
4. Add a rule to allow SSH traffic from the bastion security group we will create at the latter stage of the guide. Revisit this section after completing the bastion step.
6. For the Listeners and routing section, create two listeners for 80 and 443. Set the forwarding rule on listener 80 to redirect `http` to `https`.
1. Also, create a target group, `chatwoot-tg`, that will forward the requests to port `3000`(Chatwoot listens on this port).
2. Add a health check to the endpoint `/api`. This endpoint is not authenticated and should return the application version.
```
{
"version": "1.22.1",
"timestamp": "2021-12-06 16:07:39"
}
```
7. Add any necessary tags and click create.
### Step 6: Chatwoot Application Servers
Also, add if you have your domain on Route53 and use ACM to generate a certificate to use with ALB.
#### Launch Chatwoot Instance
## Postgresql using AWS RDS
1. Launch EC2 instance:
- **AMI**: Ubuntu 20.04 LTS
- **Instance type**: `c5.xlarge` (minimum for production)
- **VPC**: `chatwoot-vpc`
- **Subnet**: `chatwoot-private-1`
- **Auto-assign public IP**: No
- **Storage**: 60 GB GP2
- **Security group**: `chatwoot-loadbalancer-sg`
Chatwoot uses Postgres as a DB layer, and we will use Amazon RDS with a multi-AZ option for reliability.
#### Install Chatwoot
### RDS security group
1. SSH to bastion host, then to Chatwoot instance
2. Switch to root user and download installation script:
1. Navigate to EC2 > Security groups and create a new sg.
2. Name it `chatwoot-rds-sg`.
3. Select the `chatwoot-vpc` and add an inbound rule for postgres port with source `chatwoot-loadbalancer-sg`.
### RDS subnet group
1. Navigate to the RDS section and select subnet groups.
2. Create `chatwoot-rds-group` and choose `chatwoot-vpc`.
3. Select both az's and the private subnets.
### RDS
1. Select create a database.
2. Use standard create and choose the Postgres engine.
3. Use the production template, and create a Postgres master username and password.
4. Enable Multi-AZ deployment.
5. Select `chatwoot-vpc` and select the rds security group we created earlier.
6. Enable password authentication.
7. Click create.
8. After completing the creation, note down the hostname, username, and password. We will need this to configure Chatwoot.
## Redis using AWS Elasticache
1. Follow similar steps like the rds to create Redis security and subnet groups.
2. Create the Redis cluster with a multi-AZ option.
## Creating Bastion servers
Create bastion servers in both public subnets. These servers will be used to ssh into Chatwoot servers in private subnets.
1. Navigate to the EC2 dashboard and click launch instance.
2. Use an `Ubuntu 20.04 image` with a `t3.micro` type.
3. Choose `chatwoot-vpc` and subnet `chatwoot-public-1`.
4. Name it `chatwoot-bastion-a`.
5. Add a new sg, `chatwoot-bastion-sg` and enable ssh access from anywhere.
6. Leave the rest as defaults and click launch.
7. Once the instance is up, try to SSH into the instance.
Repeat and create another bastion, `chatwoot-bastion-b` in the other AZ.
## Install Chatwoot
1. Navigate to the EC2 section, and click on launch instance.
2. Use an `Ubuntu 20.04 image` with a `c5.xlarge` instance type.
3. Choose the chatwoot-vpc and select the private subnet `chatwoot-private-1`.
4. Disable auto-assign public IP and increase the storage of root volume to 60 GB.
5. Add necessary tags. Set the `Name` tag to `chatwoot`.
6. Select the load balancer security group and click launch.
7. SSH into the bastion server and, from there, ssh to the chatwoot instance we created.
8. Switch to the `root` user.
9. Download the chatwoot Linux installation script.
```bash
sudo su -
wget https://get.chatwoot.app/linux/install.sh
chmod +x install.sh
chmod 755 install.sh
```
10. Run the script.
```bash
./install.sh --install
```
#### Configure Chatwoot
## Configure Chatwoot
1. Switch to chatwoot user and edit environment:
11. Once the installation is complete, switch to the chatwoot user and navigate to the chatwoot folder. Edit the .env file and replace the Postgres and Redis credentials with RDS and elasticache values.
```bash
sudo -i -u chatwoot
cd chatwoot
nano .env
vi .env
```
2. Update database and Redis configuration:
12. Run the db migration.
```bash
# Database
DATABASE_URL="postgresql://chatwoot:password@your-rds-endpoint:5432/chatwoot_production"
# Redis
REDIS_URL="redis://your-elasticache-endpoint:6379/0"
# Frontend URL
FRONTEND_URL="https://chatwoot.yourdomain.com"
# Force SSL
FORCE_SSL=true
# Email configuration (example with SES)
MAILER_SENDER_EMAIL="noreply@yourdomain.com"
SMTP_ADDRESS="email-smtp.us-east-1.amazonaws.com"
SMTP_PORT=587
SMTP_USERNAME="your-ses-username"
SMTP_PASSWORD="your-ses-password"
SMTP_AUTHENTICATION="plain"
SMTP_ENABLE_STARTTLS_AUTO=true
# Storage (S3)
ACTIVE_STORAGE_SERVICE="amazon"
S3_BUCKET_NAME="your-chatwoot-bucket"
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"
AWS_REGION="us-east-1"
RAILS_ENV=production bundle exec rake db:prepare
```
3. Run database preparation:
13. Also modify the other necessary environment variable for your chatwoot setup. Refer to https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm#configure-the-required-environment-variables
```bash
RAILS_ENV=production bundle exec rake db:chatwoot_prepare
```
4. Restart services:
14. Restart the `chatwoot` service.
```bash
sudo cwctl --restart
```
### Step 7: SSL Certificate (ACM)
## Verify login
1. Navigate to Certificate Manager
2. Request public certificate for your domain
3. Validate domain ownership
4. Attach certificate to ALB HTTPS listener
15. Add this instance to the target group attached to the alb.
16. Navigate to your chatwoot domain to see if everything is working.
### Step 8: Auto Scaling
## Create a custom AMI
#### Create AMI
1. If you are getting the onboarding page, complete the signup and verify the installation.
2. Voila !! Your chatwoot instance is up.
3. If everything looks good, proceed to create an ami from this instance and name it `chatwoot-base-ami`.
1. Stop the Chatwoot instance
2. Create AMI named `chatwoot-base-ami`
3. Terminate the original instance
## Auto Scaling Groups (ASG)
#### Launch Template
1. Create a launch configuration using the above base image.
2. Proceed to create an auto-scaling group from this launch config.
3. Set the minimum and desired capacity to 2 and the maximum to 4. Modify this as per your requirement.
4. Create a scaling policy based on CPU utilization.
5. At this point, we are good to terminate the instance we created earlier.
6. Check the load balancer or target group to verify if two new chatwoot instances have come up.
7. That's it.
Create launch template with:
- **AMI**: `chatwoot-base-ami`
- **Instance type**: `c5.xlarge`
- **Security group**: `chatwoot-loadbalancer-sg`
- **User data** (optional):
## Monitoring
```bash
#!/bin/bash
sudo cwctl --restart
```
1. Refer to https://www.chatwoot.com/docs/self-hosted/monitoring/apm-and-error-monitoring
#### Auto Scaling Group
## Updating Chatwoot
Create ASG with:
- **Launch template**: Use created template
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets
- **Target group**: `chatwoot-tg`
- **Desired capacity**: 2
- **Minimum**: 2
- **Maximum**: 4
1. log in to one of the application servers and complete the update instructions. Run migrations if needed. Refer to https://www.chatwoot.com/docs/self-hosted/deployment/linux-vm#upgrading-to-a-newer-version-of-chatwoot
2. Create a new ami and update the launch config.
#### Scaling Policies
## Conclusion
Create scaling policies based on:
- CPU utilization (scale out at 70%, scale in at 30%)
- Memory utilization
- Request count per target
## AWS Marketplace AMI
### Quick Deployment
1. Navigate to AWS Marketplace
2. Search for "Chatwoot"
3. Subscribe to Chatwoot AMI
4. Launch instance with recommended settings:
- **Instance type**: `t3.medium` or larger
- **Storage**: 20 GB minimum
- **Security group**: Allow HTTP, HTTPS, and SSH
### Post-Launch Configuration
1. SSH to the instance
2. Complete initial setup:
```bash
sudo /opt/chatwoot/setup.sh
```
3. Configure domain and SSL:
```bash
sudo /opt/chatwoot/configure-domain.sh yourdomain.com
```
## Production Optimizations
### Performance Tuning
```bash
# Optimize Rails configuration
export RAILS_MAX_THREADS=20
export WEB_CONCURRENCY=4
export SIDEKIQ_CONCURRENCY=25
# Database connection pooling
export DATABASE_POOL_SIZE=25
```
### Monitoring Setup
#### CloudWatch Metrics
Enable detailed monitoring for:
- EC2 instances
- RDS database
- ElastiCache cluster
- Application Load Balancer
#### Custom Metrics
```bash
# Install CloudWatch agent
wget https://s3.amazonaws.com/amazoncloudwatch-agent/amazon_linux/amd64/latest/amazon-cloudwatch-agent.rpm
sudo rpm -U ./amazon-cloudwatch-agent.rpm
# Configure custom metrics
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
```
### Backup Strategy
#### RDS Automated Backups
- Enable automated backups with 7-day retention
- Configure backup window during low-traffic hours
- Enable point-in-time recovery
#### Application Data Backup
```bash
#!/bin/bash
# Backup script for application data
DATE=$(date +%Y%m%d_%H%M%S)
# Database backup
pg_dump $DATABASE_URL | gzip > "s3://your-backup-bucket/db/chatwoot_$DATE.sql.gz"
# File uploads backup (if using local storage)
aws s3 sync /home/chatwoot/chatwoot/storage s3://your-backup-bucket/storage/
```
### Security Hardening
#### IAM Roles
Create IAM roles with minimal permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::your-chatwoot-bucket/*"
},
{
"Effect": "Allow",
"Action": [
"ses:SendEmail",
"ses:SendRawEmail"
],
"Resource": "*"
}
]
}
```
#### Security Groups
Implement least-privilege access:
- ALB: Only HTTP/HTTPS from internet
- App servers: Only from ALB and bastion
- Database: Only from app servers
- Redis: Only from app servers
## Cost Optimization
### Reserved Instances
Purchase Reserved Instances for:
- RDS database instances
- ElastiCache clusters
- Predictable EC2 workloads
### Spot Instances
Use Spot Instances for:
- Development environments
- Non-critical worker processes
- Batch processing tasks
### Storage Optimization
- Use GP3 volumes for better price/performance
- Implement S3 lifecycle policies for old backups
- Use S3 Intelligent Tiering for file storage
## Troubleshooting
### Common Issues
<Accordion title="Application not accessible">
Check:
- Security group rules
- Target group health
- Route table configuration
- DNS resolution
</Accordion>
<Accordion title="Database connection errors">
Verify:
- RDS security group allows connections
- Database credentials in .env file
- Network connectivity from app servers
</Accordion>
<Accordion title="High memory usage">
Solutions:
- Increase instance size
- Optimize Sidekiq concurrency
- Enable swap memory
- Monitor for memory leaks
</Accordion>
### Monitoring Commands
```bash
# Check application health
curl -I http://localhost:3000/api
# Monitor system resources
htop
iostat -x 1
free -h
# Check service status
sudo systemctl status chatwoot.target
```
---
This AWS deployment guide provides a comprehensive approach to hosting Chatwoot on AWS infrastructure. Choose the deployment method that best fits your requirements and scale as needed.
This document is a reference guideline for an HA chatwoot architecture on AWS. Modify or build upon this to suit your requirements.