⚙️Configuration Reference
Complete guide to all FormSG environment variables, configuration options, and deployment settings.
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:
The dockerfile
.env.examplefile - Complete reference of all available variables (copy to.envfor local development)GitHub Actions Secrets - For deployment automation
AWS Systems Manager Parameter Store - For environment-specific configuration
Environment Variables - Direct configuration in your deployment environment
💡 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.
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:
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):
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
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
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
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.
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.
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_MAINTENANCEFor private form routes, only one environment variable will be read in the following precendence:
SITE_BANNER_CONTENT>ADMIN_BANNER_CONTENTFor the login page, only one environment variable will be read in the following precendence:
SITE_BANNER_CONTENT>IS_LOGIN_BANNER
AWS services
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_SDK_MODE
The mode to instantiate the sdk with.
Email and Nodemailer
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 '[email protected]'.
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.
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.
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.
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.
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.
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.
SIGNING_SECRET_KEY
The secret key for signing verified content passed into the database.
Tests
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
Last updated
Was this helpful?