Deploying to AWS

Chatmancer is deployed as a single CloudFormation stack into your AWS account. This page covers everything from IAM permissions to deleting the stack cleanly when you no longer need it.

Supported regions

Chatmancer can be deployed to any AWS region that supports all required services. We recommend picking a region close to your primary audience for lowest latency:

• us-east-1 (N. Virginia) — recommended default
• us-west-2 (Oregon)
• eu-west-1 (Ireland)
• eu-central-1 (Frankfurt)
• ap-southeast-1 (Singapore)
• ap-northeast-1 (Tokyo)

IAM permissions — the ChatMancerDeploy role

Before deploying, you need an IAM role (or user) with sufficient permissions for CloudFormation to create the stack resources. The deployment wizard will guide you through creating the ChatMancerDeploy role.

The role needs permissions to create and manage:

You only need these permissions once — during initial deploy and subsequent updates. You can restrict or delete the deploy role afterwards if you prefer.

What the CloudFormation stack creates

The stack provisions the following resources, all tagged chatmancer for easy billing attribution:

chatmancer-prod (CloudFormation Stack)
├── Lambda function            — API server (Node 22, ARM64)
├── Lambda execution role      — minimal IAM permissions
├── API Gateway HTTP API       — public HTTPS endpoint
├── CloudFront distribution    — CDN for dashboard + widget + /api/*
├── S3 bucket (assets)         — widget bundle and dashboard SPA
├── S3 bucket (documents)      — uploaded PDFs and crawled content
├── RDS PostgreSQL instance    — chatbot config, conversations, KB
├── Secrets Manager secret     — encrypted OpenAI API key
├── CloudWatch log group       — Lambda function logs
├── CloudWatch dashboard       — requests, errors, latency, costs
└── CloudWatch billing alarm   — alerts when bill exceeds your threshold

Updating the stack

When a new version of Chatmancer is released, you update by re-deploying the CloudFormation template:

1. Go to CloudFormation → Stacks → chatmancer-prod
2. Click Update
3. Choose Replace current template and use the new template URL
4. Review the change set — only Lambda code and asset buckets typically change
5. Click Execute change set

Your data (RDS, S3 documents) is never touched during an update.

Deleting the stack

To remove Chatmancer completely from your AWS account:

1. Export your data first (optional but recommended)

# Export conversations from RDS
pg_dump $DATABASE_URL > chatmancer-backup.sql

# Download documents from S3
aws s3 sync s3://your-chatmancer-documents-bucket ./backup-docs

2. Delete the stack

Go to CloudFormation → Stacks → chatmancer-prod → Delete.

CloudFormation will remove all resources it created. The deletion takes 5–10 minutes.

3. Clean up S3 buckets (if needed)

CloudFormation cannot delete S3 buckets that contain objects. If deletion fails on the bucket step, manually empty the buckets first:

aws s3 rm s3://your-chatmancer-assets-bucket --recursive
aws s3 rm s3://your-chatmancer-documents-bucket --recursive

Then retry the stack deletion.

After deletion, there are no lingering Chatmancer resources, no ongoing charges, and nothing to uninstall from your system.