### Local Development Setup Commands

Source: https://context7.com/opengovsg/formsg/llms.txt

Commands to set up a local development environment for FormSG. This includes cloning the repository, installing dependencies, copying the environment file, building frontend assets, and starting the various services.

```bash
# Clone and install
git clone https://github.com/opengovsg/FormSG.git
cd FormSG
pnpm install

# Copy environment file
cp .env.example .env   # then fill in secrets

# Build frontend assets
pnpm build:frontend

# Start all services (backend + frontend + virus scanner + PDF generator)
pnpm dev
# OR start components independently:
pnpm dev:frontend          # React dev server → http://localhost:5173
docker compose up          # backend + MongoDB + Redis → http://localhost:5001
pnpm dev:pdf-gen           # PDF generation lambda emulator
pnpm dev:virus-scanner-guardduty  # GuardDuty virus scanner emulator

# Email UI (MailDev) — http://localhost:1080
# Login via MockPass (SingPass mock): select "S9812379B [MyInfo]"
```

--------------------------------

### Install Dependencies

Source: https://github.com/opengovsg/formsg/blob/develop/packages/react-email-preview/README.md

Run this command to install the necessary project dependencies.

```sh
pnpm install
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/opengovsg/formsg/blob/develop/docs/quickstart.md

Copy the example environment file and customize it for your local setup. Default values work with Docker Compose.

```bash
# Copy the example file and customize for your environment
cp .env.example .env

# The .env file contains essential variables like:
# - Database connection settings
# - Email service configuration
# - Session security settings
# - AWS/storage service settings
```

--------------------------------

### Install Testing Prerequisites

Source: https://github.com/opengovsg/formsg/blob/develop/README.md

Install necessary node versions, package managers, and LocalStack for running tests locally. Ensure Python 3.7+ is installed for LocalStack.

```bash
nvm install
nvm use
pnpm install
pip install "localstack[full]"
```

--------------------------------

### Install FormSG JavaScript SDK

Source: https://github.com/opengovsg/formsg/blob/develop/packages/sdk/README.md

Install the SDK using npm. This command adds the necessary package to your project's dependencies.

```bash
npm install @opengovsg/formsg-sdk --save
```

--------------------------------

### Install and Use Node Version Manager

Source: https://github.com/opengovsg/formsg/blob/develop/README.md

Ensure you are using the correct Node.js version for the project by installing and switching to it using NVM.

```bash
nvm install
nvm use
```

--------------------------------

### Install and Run Multi-language Stats Script

Source: https://github.com/opengovsg/formsg/blob/develop/scripts/20220217_multi-language-stats/readme.md

Follow these steps to set up and execute the script. Ensure you copy the .env.template to .env.production and configure it with the correct URU before installing dependencies and running the data collection process.

```bash
cd scripts/multi-language-stats
cp .env.template .env.production

# edit .env.production with the correct URU

npm install
npm run get_data
```

--------------------------------

### Run Development Server

Source: https://github.com/opengovsg/formsg/blob/develop/packages/react-email-preview/README.md

Execute this command to start the development server for live email previews.

```sh
pnpm dev
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/opengovsg/formsg/blob/develop/docs/quickstart.md

Install frontend, backend, and service modules using pnpm. pnpm automatically manages the Node.js version.

```bash
pnpm install && pnpm --prefix services/virus-scanner-guardduty install && pnpm --prefix services/pdf-gen install
```

--------------------------------

### FormSG Environment Configuration Example

Source: https://context7.com/opengovsg/formsg/llms.txt

This is an example of the .env file used for configuring FormSG. It covers core application settings, email services, AWS storage, SDK mode, webhook signing, captcha, rate limits, site banners, and optional Stripe payments.

```bash
# Core application
APP_NAME=FormSG
APP_URL=https://form.example.gov
DB_HOST=mongodb://localhost:27017/formsg
PORT=5000
NODE_ENV=production
SESSION_SECRET=<random-32-char-secret>

# Email (SMTP / AWS SES)
SES_HOST=email-smtp.us-east-1.amazonaws.com
SES_PORT=465
SES_USER=AKIAIOSFODNN7EXAMPLE
SES_PASS=<smtp-password>
MAIL_FROM=donotreply@mail.example.gov

# AWS storage (S3 buckets)
AWS_REGION=ap-southeast-1
AWS_ACCESS_KEY_ID=<key>
AWS_SECRET_ACCESS_KEY=<secret>
IMAGE_S3_BUCKET=formsg-images
ATTACHMENT_S3_BUCKET=formsg-attachments
LOGO_S3_BUCKET=formsg-logos
GUARDDUTY_CLEAN_S3_BUCKET=formsg-clean
GUARDDUTY_QUARANTINE_S3_BUCKET=formsg-quarantine
GUARDDUTY_LAMBDA_FUNCTION_NAME=formsg-virus-scanner

# FormSG SDK mode (production or staging)
FORMSG_SDK_MODE=production

# Webhook signing
SIGNING_SECRET_KEY=<base64-signing-secret>
VERIFICATION_SECRET_KEY=<base64-verification-secret>

# Captcha (optional)
GOOGLE_CAPTCHA=<recaptcha-private-key>
GOOGLE_CAPTCHA_PUBLIC=<recaptcha-public-key>

# Rate limits (requests per minute per IP)
SUBMISSIONS_RATE_LIMIT=200
SEND_AUTH_OTP_RATE_LIMIT=60

# Site-wide banner (optional) — info: | warn: | error: prefix
SITE_BANNER_CONTENT=info:Scheduled maintenance on 2025-07-01 22:00–23:00 SGT.

# Stripe payments (optional)
# Configured per-form via the admin UI after Stripe OAuth Connect
```

--------------------------------

### Start AWS Session via CLI

Source: https://github.com/opengovsg/formsg/blob/develop/services/form-payment-reconciliation/README.md

Use this command to start an AWS session by providing your MFA device serial number and token code.

```bash
aws sts get-session-token --serial-number <mfa device serial number> --token-code <6 digit mfa code>
```

--------------------------------

### Example Scan Output

Source: https://github.com/opengovsg/formsg/blob/develop/docs/legal-and-compliance.md

This is an example of the output from the grep script, showing lines containing Singapore-specific keywords found in the codebase. It helps visualize the results of the scan.

```bash
# Example output
... 
   182	apps/frontend/src//features/admin-form/preview/PreviewFormPage.tsx:        <GovtMasthead />
   183	apps/frontend/.../EditMyInfoChildren.tsx:import { SINGPASS_FAQ } from '~constants/links'
   189	apps/frontend/.../EditEmail.stories.tsx:    allowedEmailDomains: ['@open.gov.sg'],
...
```

--------------------------------

### FormSG Signature Header Example

Source: https://github.com/opengovsg/formsg/blob/develop/packages/sdk/README.md

This is an example of the X-FormSG-Signature header format. Note that newlines are for clarity and a real signature is on a single line.

```text
X-FormSG-Signature: t=1582558358788,
  s=5e53ec96b10ee1010e00380b,
  f=5e4b8e3d1f61f00036c9937d,
  v1=rUAgQ9krNZspCrQtfSvRfjME6Nq4+I80apGXnCsNrwPbcq44SBNglWtA1MkpC/VhWtDeJfuV89uV2Aqi42UQBA==
```

--------------------------------

### Run Local PDF Generator Lambda

Source: https://github.com/opengovsg/formsg/blob/develop/services/pdf-gen-sparticuz/README.md

Starts the PDF generator lambda service locally. It will listen on localhost:9997.

```bash
pnpm run dev
```

--------------------------------

### Start a verification transaction for a form

Source: https://context7.com/opengovsg/formsg/llms.txt

Initiates a new transaction for verifying OTPs for form fields. Returns a transaction ID.

```bash
curl -X POST https://form.gov.sg/api/v3/forms/<formId>/fieldverifications \
  -H 'Content-Type: application/json'
```

--------------------------------

### Secure Email Service Configuration

Source: https://github.com/opengovsg/formsg/blob/develop/docs/security.md

Example configuration for a secure SMTP connection using TLS. Ensure to use app-specific passwords or tokens for authentication.

```bash
# Secure email service configuration
SES_HOST=smtp.yourorg.gov  # Your organization's SMTP server
SES_PORT=587              # TLS port
SES_USER=formsg-service   # Dedicated service account
SES_PASS=[secure-token]   # App-specific password or token
```

--------------------------------

### Run Docker Compose for Development

Source: https://github.com/opengovsg/formsg/blob/develop/docs/infrastructure-guidance.md

Command to start services defined in a Docker Compose file in detached mode. Suitable for local development and testing.

```bash
docker-compose up -d
```

--------------------------------

### Implementing English (Singapore) Translations

Source: https://github.com/opengovsg/formsg/blob/develop/TRANSLATION.md

Provides an example of implementing the translation structure for a specific locale, in this case, English (Singapore). This file defines the actual string values for the keys defined in the interface.

```typescript
// en-sg.ts - implements the structure for English
export const enSG: FieldValidation = {
  required: 'This field is required',
  invalidEmail: 'Please enter a valid email',
  // ...
};
```

--------------------------------

### Authenticate Webhooks and Decrypt Submissions with Attachments

Source: https://github.com/opengovsg/formsg/blob/develop/packages/sdk/README.md

This example demonstrates how to set up an Express.js server to receive and process FormSG webhooks. It includes authentication of the webhook signature and decryption of submission data, with support for downloading and decrypting attachments.

```javascript
// This example uses Express to receive webhooks
const express = require('express')
const app = express()

// Instantiating formsg-sdk without parameters default to using the package's
// production public signing key.
const formsg = require('@opengovsg/formsg-sdk')()

// This is where your domain is hosted, and should match
// the URI supplied to FormSG in the form dashboard
const POST_URI = 'https://my-domain.com/submissions'

// Your form's secret key downloaded from FormSG upon form creation
const formSecretKey = process.env.FORM_SECRET_KEY

// Set to true if you need to download and decrypt attachments from submissions
const HAS_ATTACHMENTS = false

app.post(
  '/submissions',
  // Endpoint authentication by verifying signatures
  function (req, res, next) {
    try {
      formsg.webhooks.authenticate(req.get('X-FormSG-Signature'), POST_URI)
      // Continue processing the POST body
      return next()
    } catch (e) {
      return res.status(401).send({ message: 'Unauthorized' })
    }
  },
  // Parse JSON from raw request body
  express.json(),
  // Decrypt the submission
  async function (req, res, next) {
    // If `verifiedContent` is provided in `req.body.data`, the return object
    // will include a verified key.
    const submission = HAS_ATTACHMENTS
      ? await formsg.crypto.decryptWithAttachments(formSecretKey, req.body.data)
      : formsg.crypto.decrypt(formSecretKey, req.body.data)

    // If the decryption failed, submission will be `null`.
    if (submission) {
      // Continue processing the submission
    } else {
      // Could not decrypt the submission
    }
  }
)

app.listen(8080, () => console.log('Running on port 8080'))

```

--------------------------------

### Build Frontend Locally

Source: https://github.com/opengovsg/formsg/blob/develop/README.md

Build the frontend for local development using pnpm.

```bash
pnpm -r --filter formsg-frontend... build
```

--------------------------------

### Configure FormSG SDK

Source: https://github.com/opengovsg/formsg/blob/develop/packages/sdk/README.md

Instantiate the SDK, specifying the environment mode. Defaults to 'production'. Use 'staging' for testing against FormSG staging servers.

```javascript
const formsg = require('@opengovsg/formsg-sdk')({
  mode: 'production',
})
```

--------------------------------

### Run Backend Unit Tests

Source: https://github.com/opengovsg/formsg/blob/develop/README.md

Build the backend and execute backend unit tests. Tests are located in the specified directory.

```bash
pnpm test
```

--------------------------------

### Connect to AWS and Login

Source: https://github.com/opengovsg/formsg/blob/develop/services/pdf-gen-sparticuz/README.md

Establishes AWS credentials by exporting the AWS_PROFILE and logging in via SSO. This is a prerequisite for deploying using AWS SAM.

```bash
export AWS_PROFILE=<profle> && aws sso login
```

--------------------------------

### Get a specific form

Source: https://context7.com/opengovsg/formsg/llms.txt

Retrieves the details of a specific form using its ID.

```bash
curl -b cookies.txt https://form.gov.sg/api/v3/admin/forms/<formId>
```

--------------------------------

### Translation Variables Example

Source: https://github.com/opengovsg/formsg/blob/develop/TRANSLATION.md

Preserve these variables, denoted by curly braces, as they are replaced at runtime.

```plaintext
Please enter at least {threshold} characters ({current}/{threshold})
```

--------------------------------

### Get a specific form

Source: https://context7.com/opengovsg/formsg/llms.txt

Retrieves the details of a specific form using its unique identifier.

```APIDOC
## GET /api/v3/admin/forms/<formId>

### Description
Retrieves the details of a specific form.

### Method
GET

### Endpoint
https://form.gov.sg/api/v3/admin/forms/<formId>
```

--------------------------------

### Build Frontend for Local Development

Source: https://github.com/opengovsg/formsg/blob/develop/docs/quickstart.md

Build the React frontend specifically for local development before running the application.

```bash
pnpm build:frontend
```

--------------------------------

### Initialize FormSG SDK

Source: https://context7.com/opengovsg/formsg/llms.txt

Instantiate the FormSG SDK with appropriate mode and optional configuration for webhook signing or OTP verification.

```typescript
import formsg from '@opengovsg/formsg-sdk'

// Production client (default) — only needs to decrypt or authenticate
const sdk = formsg({ mode: 'production' })

// Server that also sends signed webhooks
const signingSDK = formsg({
  mode: 'production',
  webhookSecretKey: process.env.FORMSG_WEBHOOK_SECRET_KEY, // base-64 encoded secret
  verificationOptions: {
    secretKey: process.env.FORMSG_VERIFICATION_SECRET_KEY,
    transactionExpiry: 14400000, // 4 hours in ms
  },
})

// SDK modules available:
// sdk.crypto      — Storage Mode v1/v2 encrypt/decrypt (NaCl box)
// sdk.cryptoV3    — Storage Mode v3 encrypt/decrypt (per-submission keypair)
// sdk.webhooks    — Webhook signature generation & authentication
// sdk.verification — OTP field signature generation & authentication
```

--------------------------------

### Start a verification transaction for a form

Source: https://context7.com/opengovsg/formsg/llms.txt

Initiates a verification transaction for a form, typically for OTP verification processes.

```APIDOC
## POST /api/v3/forms/<formId>/fieldverifications

### Description
Starts a verification transaction for a form.

### Method
POST

### Endpoint
https://form.gov.sg/api/v3/forms/<formId>/fieldverifications

### Response
#### Success Response (200)
- **transactionId** (string) - The unique identifier for the verification transaction.
```

--------------------------------

### Run End-to-End Tests (v2)

Source: https://github.com/opengovsg/formsg/blob/develop/README.md

Build frontend and backend, then run end-to-end tests. Requires stopping the Docker dev container. Tests are located in the specified directory.

```bash
pnpm test:e2e-v2
```

--------------------------------

### Get presigned S3 URLs for attachment upload before submission

Source: https://context7.com/opengovsg/formsg/llms.txt

Requests presigned S3 URLs for uploading attachments before submitting a form.

```APIDOC
## POST /api/v3/forms/<formId>/submissions/get-s3-presigned-post-data

### Description
Gets presigned S3 URLs for attachment uploads.

### Method
POST

### Endpoint
https://form.gov.sg/api/v3/forms/<formId>/submissions/get-s3-presigned-post-data

### Request Body
- **attachments** (array of objects) - Required - A list of attachments for which to get upload URLs.
  - **id** (string) - Required - The ID of the attachment.
  - **size** (integer) - Required - The size of the attachment in bytes.

### Response
#### Success Response (200)
- **fieldId1** (object) - An object containing upload URL and fields for a specific attachment.
  - **url** (string) - The presigned S3 URL.
  - **fields** (object) - The fields required for the S3 POST request.
```

--------------------------------

### Get metadata list (paginated, for the submissions table UI)

Source: https://context7.com/opengovsg/formsg/llms.txt

Retrieves a paginated list of submission metadata, suitable for display in a table UI.

```APIDOC
## GET /api/v3/admin/forms/<formId>/submissions/metadata

### Description
Retrieves a paginated list of submission metadata.

### Method
GET

### Endpoint
https://form.gov.sg/api/v3/admin/forms/<formId>/submissions/metadata

### Query Parameters
- **page** (integer) - Required - The page number for pagination.

### Response
#### Success Response (200)
- **metadata** (array of objects) - A list of submission metadata objects.
  - **number** (integer) - The submission number.
  - **id** (string) - The unique identifier of the submission.
  - **created** (string) - The creation timestamp of the submission.
  - ... (other metadata fields)
- **count** (integer) - The total number of submissions.
```

--------------------------------

### Run CI Backend Tests

Source: https://github.com/opengovsg/formsg/blob/develop/README.md

Execute backend tests optimized for continuous integration environments.

```bash
pnpm test:backend:ci
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/opengovsg/formsg/blob/develop/README.md

Execute frontend tests. The test files are located in the specified directory.

```bash
pnpm test:frontend
```

--------------------------------

### Get a single encrypted submission

Source: https://context7.com/opengovsg/formsg/llms.txt

Retrieves a single encrypted submission, including attachment download URLs. Use this to inspect or download specific submissions.

```bash
curl -b cookies.txt \
  https://form.gov.sg/api/v3/admin/forms/<formId>/submissions/<submissionId>
```

--------------------------------

### Get a single encrypted submission (includes S3 attachment signed URLs)

Source: https://context7.com/opengovsg/formsg/llms.txt

Retrieves a single encrypted submission, including signed URLs for accessing attachments.

```APIDOC
## GET /api/v3/admin/forms/<formId>/submissions/<submissionId>

### Description
Retrieves a single encrypted submission and its attachment download URLs.

### Method
GET

### Endpoint
https://form.gov.sg/api/v3/admin/forms/<formId>/submissions/<submissionId>

### Response
#### Success Response (200)
- **encryptedContent** (string) - The encrypted content of the submission.
- **verifiedContent** (string) - The verified content of the submission.
- **version** (integer) - The version of the submission format.
- **attachmentDownloadUrls** (object) - An object containing signed URLs for attachments.
```

--------------------------------

### Get Stripe client secret and publishable key

Source: https://context7.com/opengovsg/formsg/llms.txt

Retrieves Stripe client secret and publishable key required for processing a pending payment on the client side.

```bash
curl https://form.gov.sg/api/v3/payments/<paymentId>/getinfo
```

--------------------------------

### Configure Colima for x86_64 Docker Daemon

Source: https://github.com/opengovsg/formsg/blob/develop/services/pdf-gen-sparticuz/README.md

Sets up a Colima profile for x86_64 architecture and configures the DOCKER_HOST environment variable to use this daemon. This is necessary for Apple Silicon users to ensure compatibility with @sparticuz/chromium.

```bash
colima start --arch x86_64 x86
```

```bash
export DOCKER_HOST=$(docker context inspect colima-x86 --format '{{.Endpoints.docker.Host}}')
```

--------------------------------

### Get presigned S3 URLs for attachment upload

Source: https://context7.com/opengovsg/formsg/llms.txt

Requests presigned S3 URLs for uploading attachments before form submission. Specify attachment IDs and sizes.

```bash
curl -X POST https://form.gov.sg/api/v3/forms/<formId>/submissions/get-s3-presigned-post-data \
  -H 'Content-Type: application/json' \
  -d '{"attachments": [{"id": "fieldId1", "size": 204800}]}'
```

--------------------------------

### Get Stripe client secret and publishable key for a pending payment

Source: https://context7.com/opengovsg/formsg/llms.txt

Retrieves Stripe client secret and publishable key for a pending payment, used for payment processing.

```APIDOC
## GET /api/v3/payments/<paymentId>/getinfo

### Description
Gets Stripe client secret and publishable key for a pending payment.

### Method
GET

### Endpoint
https://form.gov.sg/api/v3/payments/<paymentId>/getinfo
```

--------------------------------

### Build and Deploy FormSG Docker Image

Source: https://github.com/opengovsg/formsg/blob/develop/docs/aws-production-deployment.md

Clone the FormSG repository, build the production Docker image, and then tag and push it to your AWS ECR repository. Ensure you replace placeholders with your specific account and region details.

```bash
git clone https://github.com/opengovsg/FormSG.git
cd FormSG

docker build -t formsg .

docker tag formsg:latest YOUR_ACCOUNT.dkr.ecr.REGION.amazonaws.com/formsg:latest
docker push YOUR_ACCOUNT.dkr.ecr.REGION.amazonaws.com/formsg:latest
```

--------------------------------

### Configure MinIO Self-Hosted S3 Interoperability

Source: https://github.com/opengovsg/formsg/blob/develop/docs/component-customization.md

Configure environment variables for S3 interoperability with a self-hosted MinIO instance. Ensure you have created the specified buckets in the MinIO admin console.

```bash
AWS_ENDPOINT=https://minio.yourorg.gov
AWS_ACCESS_KEY_ID=minio-admin
AWS_SECRET_ACCESS_KEY=minio-admin-password
AWS_REGION=us-east-1  # Required for S3 compatibility

# Create buckets in MinIO admin console
IMAGE_S3_BUCKET=formsg-images
ATTACHMENT_S3_BUCKET=formsg-attachments
```