Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

☁️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:

📋 Production Planning Checklist

Additional Planning for Production Deployments:

💰 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

Repository: opengovsg/formsg-on-cdk

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

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.

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:

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

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

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.

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

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

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

  • 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

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

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

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

Next Steps

Last updated