# 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="/files/UMyV8zlwPegdTSPLfR3R" 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://international.open.gov.sg/self-hosting/formsg/deployment/aws.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.