chatwoot/developer-docs/self-hosted/cloud/aws.mdx

---
title: AWS Deployment
description: Deploy Chatwoot on Amazon Web Services with manual installation or marketplace AMI
sidebarTitle: AWS
---

# AWS Deployment Guide

Deploy Chatwoot on Amazon Web Services (AWS) using either manual installation or the AWS Marketplace AMI for a scalable, production-ready setup.

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

### Prerequisites

- AWS account with appropriate permissions
- Domain name for your Chatwoot installation
- Basic knowledge of AWS services (VPC, EC2, RDS, etc.)

### Step 1: Network Setup

#### Create VPC

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

#### Create Subnets

Create subnets across two availability zones:

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

<Note>
Enable "Auto-assign public IPv4 address" for public subnets under Actions > Subnet Settings.
</Note>

#### Internet Gateway

1. Create Internet Gateway named `chatwoot-igw`
2. Attach it to `chatwoot-vpc`

#### NAT Gateways

Create NAT gateways in each public subnet:

1. **chatwoot-nat-1** in `chatwoot-public-1`
2. **chatwoot-nat-2** in `chatwoot-public-2`

Allocate Elastic IPs for each NAT gateway.

#### Route Tables

**Public Route Table** (`chatwoot-public-rt`):
- Route: `0.0.0.0/0` → `chatwoot-igw`
- Associate with public subnets

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

### Step 2: Application Load Balancer

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

#### Security Group for ALB

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)

#### Target Group

Create `chatwoot-tg` target group:
- **Target type**: Instances
- **Protocol**: HTTP
- **Port**: 3000
- **Health check path**: `/api`

### Step 3: Database Setup (RDS)

#### RDS Security Group

Create `chatwoot-rds-sg`:
- PostgreSQL (5432) from `chatwoot-loadbalancer-sg`

#### RDS Subnet Group

Create `chatwoot-rds-group`:
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets

#### Create RDS Instance

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`

<Warning>
Note down the RDS endpoint, username, and password for later configuration.
</Warning>

### Step 4: Redis Setup (ElastiCache)

#### ElastiCache Security Group

Create `chatwoot-redis-sg`:
- Redis (6379) from `chatwoot-loadbalancer-sg`

#### ElastiCache Subnet Group

Create `chatwoot-redis-group`:
- **VPC**: `chatwoot-vpc`
- **Subnets**: Both private subnets

#### Create Redis Cluster

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`

### Step 5: Bastion Host

Create bastion servers for secure access to private 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)

### Step 6: Chatwoot Application Servers

#### Launch Chatwoot Instance

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`

#### Install Chatwoot

1. SSH to bastion host, then to Chatwoot instance
2. Switch to root user and download installation script:

```bash
sudo su -
wget https://get.chatwoot.app/linux/install.sh
chmod +x install.sh
./install.sh --install
```

#### Configure Chatwoot

1. Switch to chatwoot user and edit environment:

```bash
sudo -i -u chatwoot
cd chatwoot
nano .env
```

2. Update database and Redis configuration:

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

3. Run database preparation:

```bash
RAILS_ENV=production bundle exec rake db:chatwoot_prepare
```

4. Restart services:

```bash
sudo cwctl --restart
```

### Step 7: SSL Certificate (ACM)

1. Navigate to Certificate Manager
2. Request public certificate for your domain
3. Validate domain ownership
4. Attach certificate to ALB HTTPS listener

### Step 8: Auto Scaling

#### Create AMI

1. Stop the Chatwoot instance
2. Create AMI named `chatwoot-base-ami`
3. Terminate the original instance

#### Launch Template

Create launch template with:
- **AMI**: `chatwoot-base-ami`
- **Instance type**: `c5.xlarge`
- **Security group**: `chatwoot-loadbalancer-sg`
- **User data** (optional):

```bash
#!/bin/bash
sudo cwctl --restart
```

#### Auto Scaling Group

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

#### Scaling Policies

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.