FormSG

FormSG

Features

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
Webhooks functionality via the official FormSG JavaScript SDK and contributor-supported FormSG Ruby SDK

The current product roadmap includes:

(in progress) Frontend rewrite from AngularJS to React
Enabling payments on forms
Electronic signatures
Notifications to form admins for Storage mode submissions
Integration with vault.gov.sg

Local Development (Docker)

Prerequisites

Install docker and docker-compose.

First Setup

Run npm install in root directory to install relevant npm packages.

If you are on Mac OS X, you may want to allow Docker to use more RAM (minimum of 4GB) by clicking on the Docker icon on the toolbar, clicking on the "Preferences" menu item, then clicking on the "Resources" link on the left.

If you are on macOS Monetery or higher, port 5000 is now used by the system. This conflicts with the default port used by the backend. You could either:

Update the backend ports in these environment variables:
- Dockerfile.development
  - Update exposed port
- docker-compose.yml
  - Introduce a new env var PORT
  - Update APP_URL
- frontend/package.json
  - Update the proxy URL
Disable control center

Running Locally

Run the following shell command to build the Docker image from scratch. This will usually take 10 or so minutes. This command runs the backend services specified under docker-compose.yml and the React frontend on the native host.

npm run dev

After the Docker image has finished building, the React application can be accessed at localhost:3000. The backend API server can be accessed at localhost:5001.

If there are no dependency changes in package.json or changes in the src/app/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.

Adding dependencies

Run npm install as per usual.

For backend, run

docker-compose up --build --renew-anon-volumes

which will rebuild the backend Docker image and not reuse the existing node_modules volume.

As frontend project is currently not using Docker, no other steps are required.

Accessing email locally

We use MailDev to access emails in the development environment. The MailDev UI can be accessed at localhost:1080 when the Docker container runs.

Environment variables

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 to function. More information about the required environment variables are in DEPLOYMENT_SETUP.md.

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.

Trouble-shooting

You can consult TROUBLESHOOTING.md for common issues that developers face and how to resolve them.

Testing

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.

Testing Prerequisites

The team uses macOS for development.

Make you sure have the following node version & package manager on your machine:

"node": ">=18.12.1"
"npm": ">=8.19.2"
"mongo": ">=4.0.0"

Run

nvm install 14
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.

Running tests

Unit tests

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

End-to-end tests

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

Architecture

The architecture overview is here.

MongoDB Scripts

Scripts for common tasks in MongoDB can be found here.

Contributing

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) to ensure that everybody is free to use their contributions.

Support

Please contact FormSG (support@form.gov.sg) for any details.

Acknowledgements

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
@pregnantboy
@namnguyen08
@zioul123
@JoelWee
@limli
@tankevan

thineikhaing/FormSG