⚡Quickstart

This quickstart guide helps you get FormSG running locally using Docker Compose for development and testing purposes.

Get FormSG running locally in ~30 minutes using Docker Compose.

Prerequisites

Make sure you have:

• Docker and Docker Compose (Docker Compose v2 recommended)

• Node.js v22.12 (specified in .nvmrc)

• npm or pnpm

• Node Version Manager (nvm) - highly recommended for version management

Choose Your Repository

You have two repository options:

🏛️ Standard FormSG

FormSG - Complete feature set (recommended)

git clone https://github.com/opengovsg/FormSG.git
cd FormSG

Best for:

• Most teams and deployments

• Always up-to-date with latest features and security patches

• Complete feature reference for customization

• Singapore government deployments

🌍 International Variant

Setup Steps

1

Clone the Repository

Get the FormSG source code:

git clone https://github.com/opengovsg/FormSG.git
cd FormSG

2

Install Node.js Version

Use the correct Node.js version specified in the project:

nvm install
nvm use

3

Install Dependencies

Install npm packages for frontend, backend, and virus-scanner:

npm install && npm --prefix serverless/virus-scanner install

4

Configure Environment

Copy the example environment file:

cp .env.example .env

The docker-compose.yml file contains sensible defaults for local development. Your .env file will override these when needed.

Mac users: Consider increasing Docker's RAM allocation to 4GB minimum via Docker Desktop → Preferences → Resources.

5

Build Frontend

Build the React frontend for development:

npm run build:frontend

Verify the build succeeded:

ls -la dist/frontend

You should see the built frontend files in the dist/frontend directory.

6

Start Development Environment

Launch all services:

npm run dev

This command:

• Builds and runs backend services via Docker Compose

• Starts the React frontend on your host machine

• First run takes ~10 minutes to download and build images

Wait for all services to start completely.

Troubleshooting

Need to restart?

If you need to start over from scratch:

# Stop and remove all containers, networks, and orphaned containers
docker compose down --remove-orphans

# Optionally remove volumes (clears database data)
docker compose down --remove-orphans --volumes

Then restart from Step 1.

Accessing FormSG

Once everything is running, access your local FormSG instance:

• Frontend: http://localhost:5173 - Main FormSG application

• Backend API: http://localhost:5001 - API server

• Mail Server: http://localhost:1080 - Development email interface

✅ Success Check: If you can access http://localhost:5173 and see the FormSG interface, your local setup is working correctly!

Accessing email locally

FormSG uses MailDev for email testing in development. Access the MailDev interface at http://localhost:1080 to:

• View all emails sent by FormSG (OTP codes, form submissions, etc.)

• Test email workflows without sending real emails

• Debug email templates and formatting

Login using MockPass locally

FormSG includes MockPass for simulating government authentication:

1. On the login page, click "Login with Singpass"

2. Select any test profile from the dropdown (e.g., S9812379B [MyInfo])

3. Complete the mock authentication flow

4. You'll be logged in as a test user

For production: Replace MockPass with your country's actual identity provider integration. See Component Customization for guidance.

Adding dependencies

Run npm install as per usual.

For backend dependencies, rebuild the containers:

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

This rebuilds the backend Docker image with fresh node_modules.

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

Environment Variable Priority

Docker-compose looks at various places for environment variables in this order of priority:

1. Compose file

2. Shell environment variables

3. Environment file (.env)

4. Dockerfile

The .env file you created from .env.example will provide the default configuration for local development. For production deployments, you'll need to customize these values according to your infrastructure and security requirements.