Form builder for the Singapore Government
For comprehensive self-hosting guides, configuration references, and deployment instructions, visit our FormSG Self-Hosting Guide.
The GitBook documentation is actively maintained and provides:
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 will also be asked to sign a Contributor License Agreement (CLA) to ensure that everybody is free to use their contributions.
Before contributing, please read CONTRIBUTING.md. In particular, we strongly encourage contributors to please first discuss the change you wish to make via GitHub issue, email, or any other method with the repository owners beforehand. Otherwise, we may not be able to review or accept your PR.
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:
@opengovsg/formsg-sdk from packages/sdk) and contributor-supported FormSG Ruby SDKInstall docker and docker-compose and the node version manager.
First, make sure to install and use the node version used by the project:
nvm install
nvm useTo install the relevant packages (frontend, backend, services including pdf-generator and virus-scanner), run the following in the root directory:
pnpm installIf 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.
First, build the frontend for local development:
pnpm -r --filter formsg-frontend... buildRun the following shell commands to build the Docker image. The first time will usually take 10 or so minutes. These commands runs the backend services specified under docker-compose.yml and the React frontend on the native host.
This command runs:
pnpm devAlternatively, you can run required components independently - which is what the main dev team usually does:
# Frontend server
pnpm dev:frontend (frontend react server, compulsory)
# Backend server
docker compose up
# PDF generation function (only needed if you're using features requiring PDF generation, eg, payment invoice/auto-reply PDF)
pnpm dev:pdf-gen
# Virus scanners - run both (only needed if you're uploading attachments)
pnpm dev:virus-scanner-guarddutyAfter the Docker image has finished building, the following local applications can be accessed:
Run pnpm add as per usual.
For backend, run
docker-compose up --build --renew-anon-volumeswhich 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.
We use MailDev to access emails in the development environment. The MailDev UI can be accessed at http://localhost:1080 when the Docker container runs.
Login with Singpass button on the login pageS9812379B [MyInfo][email protected]Note: Remember to renew your formsg_mongodb_data volume
Docker-compose looks at various places for environment variables to inject into the containers. The following is the order of priority:
FormSG requires some environment variables to function. More information about the required environment variables are in the Configuration Reference.
We provide a .env.example 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.
For troubleshooting common development issues, refer to the Self-Hosting Guide or create an issue in the repository.
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": ">=22.12.0""pnpm": ">=10.30.3""mongo": ">=4.0.0"Run
nvm install
nvm use
pnpm 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.
pnpm testwill build the backend and run our backend unit tests. The tests are located at __tests__/unit/backend.
For CI testing (optimized for continuous integration), you can run
pnpm test:backend:ciFrontend tests are located at apps/frontend/__tests__. They can be run with
pnpm test:frontendpnpm test:e2e-v2will build both the frontend and backend then run our end-to-end tests. The tests are located at __tests__/e2e. 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
pnpm exec playwright testThis project is tested with BrowserStack.
The architecture overview is available in the Self-Hosting Guide.
Please contact FormSG ([email protected]) for any details.
FormSG uses MongoDB with Mongoose ODM. While the application can potentially be adapted to work with other databases, this requires significant code changes and is not officially supported.
For detailed guidance on database migration options (including FerretDB, Prisma ORM, CockroachDB, and other alternatives), refer to the Self-Hosting Guide.
Note: Database migrations involve complex changes to the codebase and may require ongoing maintenance. Consider the trade-offs carefully before proceeding.
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
No open issues yet, or sync has not completed.