☁️AWS

This guide helps you deploy FormSG to production using standard AWS services with minimal customisation. For teams wanting to get FormSG running quickly in an AWS environment.

Quick Start Prerequisites

Before deploying FormSG to AWS:

• AWS Account with administrative access

• Domain name you control (e.g., forms.yourorg.gov)

• Basic AWS knowledge (familiarity with AWS Console)

📋 Production Planning Checklist

Additional Planning for Production Deployments:

• SSL certificate strategy (CDK can create automatically or use existing)

• Estimated user load (concurrent users, forms per day)

• Email provider setup (AWS SES domain verification)

• Database strategy (MongoDB Atlas vs self-hosted)

• Security and compliance requirements documented

• Budget approved for ongoing AWS infrastructure costs

💰 Budget Planning:

Government teams typically need cost estimates for approval:

• Compute costs: Vary by region and usage (ECS Fargate pricing)

• Database costs: MongoDB Atlas M10+ or self-hosted infrastructure

• Storage & networking: S3, data transfer, and load balancer costs

For planning purposes: Small government deployments (few hundred daily users) typically cost $100-400/month depending on region and configuration.

Use the AWS Pricing Calculator with your specific requirements for accurate estimates.

FormSG Production Architecture

This guide deploys the complete FormSG architecture to AWS:

AWS Infrastructure Implementation

The FormSG components map to AWS services as follows:

• Frontend & API: ECS containers behind Application Load Balancer

• Database: MongoDB Atlas or self-hosted MongoDB on EC2

• Object Storage: S3 buckets with encryption

• Email Service: AWS SES with SMTP

• Identity Provider: AWS Cognito or external SAML/OIDC

• Monitoring: CloudWatch + optional Datadog

• Container Platform: ECS

🌟 Quick Deployment with CDK Template

Recommended Approach: Use the official FormSG CDK template for faster path to deployment.

Why Use the Template?

The FormSG team provides an AWS-ready CDK template that includes:

• Infrastructure - VPC, ECS, S3, ALB, CloudWatch, and monitoring

• Security configurations - Network isolation, encryption, and access controls

• Automated SSL - Certificate management and renewal

• Cost optimized - Right-sized resources for typical government workloads

Getting Started

Quick Start

Repository: opengovsg/formsg-on-cdk

# 1. Clone the official template
git clone https://github.com/opengovsg/formsg-on-cdk.git
cd formsg-on-cdk

# 2. Install dependencies
npm install

# 3. Deploy to AWS
npx cdk bootstrap  # First time only
npx cdk deploy

Deployment time: 15-30 minutes for complete infrastructure setup.

Configuration

Essential Settings (configure after deployment):

The CDK template will prompt you for or you'll need to configure:

• Domain name - Your FormSG domain (e.g., forms.yourorg.gov)

• MongoDB connection - Atlas cluster or self-hosted database URL

• Email settings - AWS SES SMTP configuration for your domain

• SSL certificate - CDK can create this automatically or use existing

What to prepare:

• Domain name you control

• MongoDB Atlas cluster (recommended) or self-hosted MongoDB

• AWS SES domain verification for email delivery

Refer to the CDK template documentation for specific configuration steps.

Post-Deployment

After deployment completes:

1. Verify deployment: Check the CDK outputs for your application URL

2. Test login: Visit admin portal and test email OTP delivery

3. Configure DNS: Point your domain to the provided load balancer

4. Set up monitoring: Review CloudWatch dashboards created automatically

CDK Outputs include:

• Application Load Balancer DNS name

• ECS cluster name

• S3 bucket names

• CloudWatch log groups

CDK Template Documentation

For detailed configuration options, troubleshooting, and advanced features:

• Project Wiki: CDK Template Documentation

• Issues & Support: GitHub Issues

Fastest Path: The CDK template provides the quickest way to get FormSG running on AWS with tested configurations.

Can't Use the CDK Template?

The CDK template above is the publicly available approach for AWS deployment. However, if you have specific constraints:

Alternative Approaches

Other IaC Tools

If your organization requires different Infrastructure as Code:

Terraform/Pulumi/CloudFormation (2-4 weeks additional effort):

• Start with cdk synth to see the generated CloudFormation resources

• Adapt the resource definitions to your preferred tool

• See Infrastructure Guidance for architectural patterns

These approaches require significant additional work and technical expertise.

Non-AWS Deployment

If you can't use AWS:

• Other cloud providers: See Infrastructure Guidance for multi-cloud patterns

• Smaller scale: Consider VM Deployment for simpler infrastructure needs

• Hybrid approach: Start with VM deployment, migrate to cloud when ready

FormSG's architecture is cloud-agnostic but requires adaptation work for non-AWS platforms.

Learning & Understanding

If you want to understand the infrastructure:

• Review the "Understanding What Gets Created" section below

• Check Infrastructure Guidance for detailed architectural patterns

• Consider VM Deployment for hands-on learning with simpler setup

• 2Use AWS Console (ClickOps) to manually + explore the components created by CDK

Recommended learning path: Start with VM deployment to understand FormSG, then move to CDK template for production.

Understanding What Gets Created

The CDK template automatically sets up a complete FormSG infrastructure including:

• Networking: VPC with public/private subnets, load balancer, security groups

• Compute: ECS cluster with auto-scaling containers

• Storage: S3 buckets for files, Parameter Store for configuration

• Database: Connection to your MongoDB (Atlas or self-hosted)

• Email: Integration with AWS SES for notifications

• Monitoring: CloudWatch logs, metrics, and basic alarms

• Security: SSL certificates, encryption, network isolation

Architecture Details

Network

• VPC with public and private subnets

• Application Load Balancer in public subnets (internet-facing)

• ECS containers in private subnets (internal only)

• Security groups with least-privilege access (ALB → ECS → Database)

Application

• ECS cluster with Fargate for serverless container management

• Auto-scaling group (2-10 containers based on CPU/memory)

• Application Load Balancer with SSL termination and health checks

• ECR repository for FormSG container images

Data

• MongoDB Atlas integration (recommended) or self-hosted MongoDB

• S3 buckets for form attachments, images, and static assets

• AWS Parameter Store for environment variables

• AWS Secrets Manager for sensitive credentials (database passwords, API keys)

External Services

• AWS SES for email delivery with DKIM/SPF configuration

• Route 53 or external DNS for domain management

• AWS Certificate Manager for SSL certificate automation

• CloudWatch for logging, metrics, alarms, and cost monitoring

This architecture provides high availability, security, and scalability suitable for government production workloads.

Validation Checklist

1. Check CDK outputs for your application URL

2. Visit your FormSG domain and proceed with functional testing:

• Login with email OTP

• Create and publish a test form

• Submit form as citizen user

Issues? Check CloudWatch logs for your ECS service. Common problems: MongoDB connection, SES verification, DNS configuration.

Next Steps

🎉 Success! Your FormSG production deployment is now running on AWS.

Recommended next steps:

• Set up automated backups for your database

• Review security settings and compliance requirements