# AWS

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

<details>

<summary><strong>📋 Production Planning Checklist</strong></summary>

**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](https://calculator.aws/) with your specific requirements for accurate estimates.

</details>

### FormSG Production Architecture

This guide deploys the complete FormSG architecture to AWS:

<figure><img src="https://3225095994-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFiAVh1Ff3KUiYxMAZuJG%2Fuploads%2FsCNmoCABlx9kYtFUc3UG%2Fimage.png?alt=media&#x26;token=d9ebf561-8a54-44c9-b2df-bfa7e6fae50c" alt=""><figcaption></figcaption></figure>

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

{% tabs %}
{% tab title="Quick Start" %}
**Repository**: [opengovsg/formsg-on-cdk](https://github.com/opengovsg/formsg-on-cdk)

```bash
# 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.
{% endtab %}

{% tab title="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](https://github.com/opengovsg/formsg-on-cdk/wiki) for specific configuration steps.
{% endtab %}

{% tab title="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
  {% endtab %}
  {% endtabs %}

#### CDK Template Documentation

For detailed configuration options, troubleshooting, and advanced features:

* **Project Wiki**: [CDK Template Documentation](https://github.com/opengovsg/formsg-on-cdk/wiki)
* **Issues & Support**: [GitHub Issues](https://github.com/opengovsg/formsg-on-cdk/issues)

{% hint style="success" %}
**Fastest Path**: The CDK template provides the quickest way to get FormSG running on AWS with tested configurations.
{% endhint %}

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

{% tabs %}
{% tab title="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

{% hint style="warning" %}
These approaches require significant additional work and technical expertise.
{% endhint %}
{% endtab %}

{% tab title="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

{% hint style="info" %}
FormSG's architecture is cloud-agnostic but requires adaptation work for non-AWS platforms.
{% endhint %}
{% endtab %}

{% tab title="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

{% hint style="success" %}
**Recommended learning path**: Start with VM deployment to understand FormSG, then move to CDK template for production.
{% endhint %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="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)
  {% endtab %}

{% tab title="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
  {% endtab %}

{% tab title="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)
  {% endtab %}

{% tab title="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
  {% endtab %}
  {% endtabs %}

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

{% hint style="success" %}
**🎉 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
  {% endhint %}