FormSG is a form builder application built, open sourced and maintained by the Open Government Products team of the Singapore Government Technology Agency to digitise paper processes.
Notable features include:
- 19 different form field types, including attachments, tables, email and mobile
- Verified email and mobile phone fields via integrations with Twilio and AWS SES
- Automatic emailing of submissions for forms built with Email Mode
- End-to-end encryption for forms built with Storage Mode
- (Singapore government agencies only) Citizen authentication with SingPass
- (Singapore government agencies only) Corporate authentication with CorpPass
- (Singapore government agencies only) Automatic prefill of verified data with MyInfo
- (beta) Webhooks functionality via the FormSG JavaScript SDK.
The current product roadmap includes:
- (in progress) Migrating backend code from JavaScript to TypeScript
- (in progress) Refactoring backend code to use Domain-driven Design
- (in progress) Migrating backend tests from Jasmine to Jest and expanding unit vs integration tests
- (yet to start) Support for webhooks attachments
- (yet to start) Frontend rewrite from AngularJS to React
Install docker and docker-compose.
Run the following shell command to build the Docker image from scratch. This will usually take 10 or so minutes.
npm run dev
After the Docker image has finished building, the application can be accessed at localhost:5000.
If there have been no dependency changes in package.json
or changes in the
src/server.ts
file, you can run
docker-compose up
which does not rebuild the Docker image from scratch. This command usually only takes ~15 seconds to finish starting up the image.
We use MailDev to access emails in the development environment. The MailDev UI can be accessed at localhost:1080 when the Docker container is running.
Docker-compose looks at various places for environment variables to inject into the containers. The following is the order of priority:
- Compose file
- Shell environment variables
- Environment file
- Dockerfile
FormSG requires some environment variables in order to function. More information about the required environment variables can be seen in DEPLOYMENT_SETUP.md.
The docker-compose file declares some blank environment variables that are secret and cannot be committed into the repository. See below instructions to get them injected into the container.
We provide a .template-env
file with the secrets blanked out. You can copy and
paste the variables described into a self-created .env
file, replacing the
required values with your own.
You can consult TROUBLESHOOTING.md for common issues that developers face and how to resolve them.
The docker environment has not been configured to run tests. Thus, you will need to follow the following local build guide to get tests running locally.
The team uses macOS for development.
Make you sure have the following node version & package manager on your machine:
"node": ">=12.18.0"
"npm": ">=6.0.0"
"mongo": ">=3.6.0"
Run
nvm install 12.18.0
npm install
pip install "localstack[full]"
to install node modules and Localstack locally to be able to run tests. Note that
localstack[full]
is only compatible with Python 3.7 and above.
npm run test
will build the backend and run both our backend and frontend unit tests. The tests are located at
tests/unit/frontend
and
tests/unit/backend
.
If the backend is already built, you can run
npm run test-ci
npm run test-e2e
will build both the frontend and backend then run our end-to-end tests. The tests are located at tests/end-to-end
. You will need to stop the Docker dev container to be able to run the end-to-end tests.
If you do not need to rebuild the frontend and backend, you can run
npm run test-e2e-ci
An overview of the architecture can be found here.
Scripts for common tasks in MongoDB can be found here.
Banners providing form-fillers with useful information can shown at the top of forms and configured using the environment variables below.
Environment Variable | Value will be shown as a banner at the bottom of |
---|---|
ADMIN_BANNER_CONTENT |
private form routes such as /forms and /{formId}/admin |
SITE_BANNER_CONTENT |
both private routes that ADMIN_BANNER_CONTENT covers and public form routes that IS_GENERAL_MAINTENANCE covers. This supersedes ALL other banner environment variables |
IS_GENERAL_MAINTENANCE |
all public 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
We welcome all contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas to code open sourced by the Government Technology Agency of Singapore. Contributors should read CONTRIBUTING.md and will also be asked to sign a Contributor License Agreement (CLA) in order to ensure that everybody is free to use their contributions.
Please contact FormSG ([email protected]) for any details.
FormSG acknowledges the work done by Arielle Baldwynn to build and maintain TellForm, on which FormSG is based.
Contributions have also been made by:
@RyanAngJY
@jeantanzy
@yong-jie
@pregnantboy
@namnguyen08
@zioul123
@JoelWee
@limli
@tankevan
@LoneRifle