configuration-reference.md

description	Complete guide to all FormSG environment variables, configuration options, and deployment settings.

⚙️ Configuration Reference

This is a comprehensive reference document containing all available FormSG configuration options, referenced from existing documentation inside the codebase.

FormSG is designed to be highly configurable through environment variables, allowing for customization and adaptation to different deployment environments.

Configuration Sources

FormSG configuration comes from multiple sources depending on your deployment approach:

1. .env.example file - Complete reference of all available variables (copy to .env for local development)
2. GitHub Actions Secrets - For deployment automation
3. AWS Systems Manager Parameter Store - For environment-specific configuration
4. Environment Variables - Direct configuration in your deployment environment

{% hint style="success" %} 💡 Quick Start: The .env.example file in the FormSG repository contains all available configuration options with example values. Copy this file to .env and customize the values for your environment. {% endhint %}

This document details all available configuration options, organized by category, to help you set up your FormSG instance correctly.

Github Actions Secrets

The following repository secrets are set in Github Actions:

Secret	Description
AWS_ACCESS_KEY_ID	AWS IAM access key ID used to deploy.
AWS_SECRET_ACCESS_KEY	AWS IAM access secret used to deploy.
AWS_DEFAULT_REGION	AWS region to use.
ECR_REPO	ECR Repository which stores the docker images.
BUCKET_NAME	S3 Bucket used to store zipped Dockerrun.aws.json.

There are also environment secrets for each environment (staging, staging-alt, release, uat):

Secret	Description
APP_NAME	Application name for the environment.
DEPLOY_ENV	Deployment environment on elastic beanstalk.
REACT_APP_FORMSG_SDK_MODE	Determines the keys used in the formsg SDK. Set either production or staging.

Environment Variables

These are configured by creating groups of environment variables formatted like .env files in the Parameter Store of AWS Service Manager. These groups have names formatted as <environment>-<category>.

Core Features

AWS Systems Manager

Variable	Description
SECRET_ENV	String (typically the environment type) to be used in building of AWS Secrets Manager keys in different environments.
SSM_ENV_SITE_NAME	String (the specific environment site name) to be used in building of AWS Secrets Manager keys in different environments. (staging, staging-alt, staging-alt2, prod, uat)

App Config

Variable	Description
APP_NAME	Application name in window title; also used as an identifier for MyInfo. Defaults to 'FormSG'.
APP_DESC	Defaults to 'Form Manager for Government'.
APP_URL	Defaults to 'https://form.gov.sg'.
APP_KEYWORDS	Defaults to 'forms, formbuilder, nodejs'.
APP_IMAGES	Defaults to '/public/modules/core/img/og/img_metatag.png,/public/modules/core/img/og/logo-vertical-color.png'.
APP_TWITTER_IMAGE	Path to Twitter image. Defaults to '/public/modules/core/img/og/logo-vertical-color.png'.

App and Database

Variable	Description
DB_HOST	A MongoDB URI.
OTP_LIFE_SPAN	Time in milliseconds that admin login OTP is valid for. Defaults to 900000ms or 15 minutes.
PORT	Server port. Defaults to 5000.
NODE_ENV	Express environment mode. Defaults to 'production'. This should always be set to a production environment
SESSION_SECRET	Secret for express-session for session management. This should always be set to a secret and random value in a production environment.
SUBMISSIONS_TOP_UP	Use this to inflate the number of submissions displayed on the landing page. Defaults to 0.
FORMS_TOP_UP	Use this to inflate the number of submissions displayed on the landing page. Defaults to 0.

Banners

These environment variables allow us to set notification banners in the application without a full redeployment of the application. Note the hierarchy of the banner content.

In addition, you can change the color of the banner by adding a type encoding in the environment variable string. The default banner type will be info if no encoding is provided.

The possible banner type prefixes are: info:, warn:, and error:. Other prefixes will not work and the invalid prefixes will be shown in the banner text.

Examples:

SITE_BANNER_CONTENT=info:This is an info banner. You can also add links in the text like https://example.com. There is also a dismiss button to the right of the text.

SITE_BANNER_CONTENT=warn:This is a warning banner. You can also add links in the text like https://example.com

SITE_BANNER_CONTENT=error:This is an error banner. You can also add links in the text like https://example.com

SITE_BANNER_CONTENT=hello:This is an invalid banner type, and the full text will be shown. The default banner type of `info` will used.

Variable	Description
SITE_BANNER_CONTENT	If set, displays a banner message on both private routes that ADMIN_BANNER_CONTENT covers and public form routes that IS_GENERAL_MAINTENANCE covers. Overrides all other banner environment variables
ADMIN_BANNER_CONTENT	If set, displays a banner message on private admin routes such as the form list page as well as form builder pages.
IS_LOGIN_BANNER	If set, displays a banner message on the login page.
IS_GENERAL_MAINTENANCE	If set, displays a banner message on all forms. Overrides IS_SP_MAINTENANCE and IS_CP_MAINTENANCE.
MYINFO_BANNER_CONTENT	all public MyInfo-enabled forms
IS_SP_MAINTENANCE	all public Singpass-enabled forms
IS_CP_MAINTENANCE	all public Corppass-enabled forms

Note that if more than one of the above environment variables are defined, only one environment variable will be used to display the given values.

For public form routes, only one environment variable will be read in the following precedence: SITE_BANNER_CONTENT > IS_GENERAL_MAINTENANCE > IS_SP_MAINTENANCE > IS_CP_MAINTENANCE

For private form routes, only one environment variable will be read in the following precendence: SITE_BANNER_CONTENT > ADMIN_BANNER_CONTENT

For the login page, only one environment variable will be read in the following precendence: SITE_BANNER_CONTENT > IS_LOGIN_BANNER

AWS services

Variable	Description
AWS_REGION	AWS region.
AWS_ACCESS_KEY_ID	AWS IAM access key ID used to access S3.
AWS_SECRET_ACCESS_KEY	AWS IAM access secret used to access S3.
AWS_ENDPOINT	AWS S3 bucket endpoint.
IMAGE_S3_BUCKET	Name of S3 bucket for image field uploads.
STATIC_ASSETS_S3_BUCKET	Name of S3 bucket for static assets.
LOGO_S3_BUCKET	Name of S3 bucket for form logo uploads.
GUARDDUTY_QUARANTINE_S3_BUCKET	Name of S3 bucket for quarantined files.
GUARDDUTY_CLEAN_S3_BUCKET	Name of S3 bucket for clean files.
GUARDDUTY_LAMBDA_FUNCTION_NAME	Name of AWS Lambda function for GuardDuty malware scanning.
ATTACHMENT_S3_BUCKET	Name of S3 bucket for attachment uploads on Storage Mode.
CUSTOM_CLOUDWATCH_LOG_GROUP	Name of CloudWatch log group to send custom logs. Use this if you want some logs to have custom settings, e.g. shorter expiry time.

FormSG JavaScript SDK

Variable	Description
FORMSG_SDK_MODE	The mode to instantiate the sdk with.

Email and Nodemailer

Variable	Description
SES_HOST	SMTP hostname.
SES_PORT	SMTP port number.
SES_USER	SMTP username.
SES_PASS	SMTP password.
SES_MAX_MESSAGES	Nodemailer configuration. Connection removed and new one created when this limit is reached. This helps to keep the connection up-to-date for long-running email messaging. Defaults to 100.
SES_POOL	Connection pool to send email in parallel to the SMTP server. Defaults to 38.
MAIL_FROM	Sender email address. Defaults to 'donotreply@mail.form.gov.sg'.
MAIL_SOCKET_TIMEOUT	Milliseconds of inactivity to allow before killing a connection. This helps to keep the connection up-to-date for long-running email messaging. Defaults to 600000.
MAIL_LOGGER	If set to true then logs to console. If value is not set or is false then nothing is logged.
MAIL_DEBUG	If set to true, then logs SMTP traffic, otherwise logs only transaction events.
CHROMIUM_BIN	Filepath to chromium binary. Required for email autoreply PDF generation with Puppeteer.
BOUNCE_LIFE_SPAN	Time in milliseconds that bounces are tracked for each form. Defaults to 86400000ms or 24 hours. Only relevant if you have set up AWS to send bounce and delivery notifications to the /emailnotifications endpoint.

Rate limits at specific endpoints

The app applies per-minute, per-IP rate limits at specific API endpoints as a security measure. The limits can be specified with the following environment variables.

Variable	Description
SUBMISSIONS_RATE_LIMIT	Per-minute, per-IP request limit for each submissions endpoint. The limit is applied separately for the email mode and encrypt mode endpoints.
SEND_AUTH_OTP_RATE_LIMIT	Per-minute, per-IP request limit for the endpoint which requests for new login OTPs for the admin console or mobile / email field verifications.

Additional Features

The app contains a number of additional features like Captcha protection. Each of these features requires specific environment variables which are detailed below.

Google Captcha

Forms can be protected with recaptcha, preventing submissions from being made by bots.

Variable	Description
GOOGLE_CAPTCHA	Google Captcha private key
GOOGLE_CAPTCHA_PUBLIC	Google Captcha public key.

SMS

The Mobile Number field supports form-fillers verifying their mobile numbers via a One-Time-Pin sent to their mobile phones.

All messages are sent using Postman, a government communications service developed by the Open Government Products team. This Postman service (not to be confused with the popular API client of the same name) is specifically designed for Singapore government agencies to send SMS messages to citizens and businesses. It provides campaign management, delivery tracking, and compliance with government communication standards.

Note that verifying mobile numbers also requires the environment variables for verified Emails/SMSes.

Variable	Description
POSTMAN_MOP_CAMPAIGN_ID	Campaign ID for MOP (Member of Public) SMS
POSTMAN_MOP_CAMPAIGN_API_KEY	API key for MOP campaign
POSTMAN_INTERNAL_CAMPAIGN_ID	Campaign ID for internal SMS
POSTMAN_INTERNAL_CAMPAIGN_API_KEY	API key for internal campaign
POSTMAN_BASE_URL	Base URL for Postman API (e.g., https://test.postman.gov.sg/api/v2)
USE_MOCK_POSTMAN_SMS	Boolean flag for development/testing

Singpass/Corppass and MyInfo

Submissions can be authenticated via Singpass (Singapore's Digital Identity for Citizens) and Corppass (Singapore's Digital Identity for Organizations). Forms can also be pre-filled using MyInfo after a citizen has successfully authenticated using Singpass.

Note that MyInfo is currently not supported for storage mode forms and enabling Singpass/Corppass on storage mode forms also requires Singpass/Corppass for Storage Mode to be enabled.

Variable	Description
SPCP_COOKIE_MAX_AGE_PRESERVED	Duration of Singpass JWT before expiry in milliseconds. Defaults to 30 days.
SINGPASS_ESRVC_ID	e-service ID registered with National Digital Identity office for Singpass authentication. Needed for MyInfo.
SP_OIDC_NDI_DISCOVERY_ENDPOINT	NDI's Singpass OIDC Discovery Endpoint
SP_OIDC_NDI_JWKS_ENDPOINT	NDI's Singpass OIDC JWKS Endpoint
SP_OIDC_RP_CLIENT_ID	The Relying Party's Singpass Client ID as registered with NDI
SP_OIDC_RP_REDIRECT_URL	The Relying Party's Singpass Redirect URL
SP_OIDC_RP_JWKS_PUBLIC_PATH	Path to the Relying Party's Public Json Web Key Set used for Singpass-related communication with NDI. This will be hosted at /sp/.well-known/jwks.json endpoint.
SP_OIDC_RP_JWKS_SECRET_PATH	Path to the Relying Party's Secret Json Web Key Set used for Singpass-related communication with NDI
CP_OIDC_NDI_DISCOVERY_ENDPOINT	NDI's Corppass OIDC Discovery Endpoint
CP_OIDC_NDI_JWKS_ENDPOINT	NDI's Corppass OIDC JWKS Endpoint
CP_OIDC_RP_CLIENT_ID	The Relying Party's Corppass Client ID as registered with NDI
CP_OIDC_RP_REDIRECT_URL	The Relying Party's Corppass Redirect URL
CP_OIDC_RP_JWKS_PUBLIC_PATH	Path to the Relying Party's Public Json Web Key Set used for Corppass-related communication with NDI. This will be hosted at api/v3/corppass/.well-known/jwks.json endpoint.
CP_OIDC_RP_JWKS_SECRET_PATH	Path to the Relying Party's Secret Json Web Key Set used for Corppass-related communication with NDI
MYINFO_CLIENT_CONFIG	Configures MyInfoGovClient. Set this to eitherstg or prod to fetch MyInfo data from the corresponding endpoints.
MYINFO_FORMSG_KEY	Filepath to MyInfo private key, which is used to decrypt data and sign requests when communicating with MyInfo.
MYINFO_CERT	Path to MyInfo's public certificate, which is used to verify their signature.
MYINFO_CLIENT_ID	Client ID registered with MyInfo.
MYINFO_CLIENT_SECRET	Client secret registered with MyInfo.
MYINFO_JWT_SECRET	Secret for signing MyInfo JWT.
IS_SP_MAINTENANCE	If set, displays a banner message on Singpass forms. Overrides IS_CP_MAINTENANCE.
IS_CP_MAINTENANCE	If set, displays a banner message on Corppass forms.

Verified Emails/SMSes

The Mobile Number and Email fields support form-fillers verifying their contact details via a One-Time-Pin.

Note that verified SMSes also require SMS to be enabled.

Variable	Description
VERIFICATION_SECRET_KEY	The secret key for signing verified responses (email, mobile).

Webhooks and Singpass/Corppass for Storage Mode

Form admins can configure their Storage mode forms to POST encrypted form submissions to a REST API supplied by the form creator. The FormSG SDK can then be used to verify the signed posted data and decrypt the encrypted submission contained within.

These environment variables also allow Storage mode forms to support authentication via Singpass or Corppass. Note that this also requires Singpass/Corppass and MyInfo to be enabled.

Variable	Description
SIGNING_SECRET_KEY	The secret key for signing verified content passed into the database.

Tests

Variable	Description
MONGO_BINARY_VERSION	Version of the Mongo binary used. Defaults to 'latest' according to MongoMemoryServer docs.
PWD	Path of working directory.
MOCK_WEBHOOK_CONFIG_FILE	Path of configuration file for mock webhook server
MOCK_WEBHOOK_PORT	Port of mock webhook server