# Quickstart

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

### Prerequisites

Make sure you have:

* [Docker and Docker Compose](https://docs.docker.com/get-docker/) (Docker Compose v2 recommended)
* [Node.js](https://nodejs.org/) v22.12 (specified in `.nvmrc`)
* [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/)
* [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm) - highly recommended for version management

#### Choose Your Repository

You have two repository options:

{% tabs %}
{% tab title="🏛️ Standard FormSG" %}
**FormSG** - Complete feature set (recommended)

```bash
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
  {% endtab %}

{% tab title="🌍 International Variant" %}
**FormSG International** - Singapore-specific features removed

```bash
git clone https://github.com/opengovsg/formsg-intl.git
cd formsg-intl
```

After cloning, read the [README](https://github.com/opengovsg/formsg-intl) of the repo to patch over the `replacements` folder

**Best for:**

* International teams wanting a cleaner starting point
* Deployments that don't need Singapore-specific integrations
* Teams preferring to start without Singapore-specific code

{% hint style="warning" %}
The formsg-intl repository removes most Singapore-specific features and branding.

Note that the code implementing these features may still be present, so you are free to remove them, or study them to understand how you might build equivalent features in your local context.
{% endhint %}
{% endtab %}
{% endtabs %}

### Setup Steps

{% stepper %}
{% step %}

#### Clone the Repository

Get the FormSG source code:

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

{% endstep %}

{% step %}

#### Install Node.js Version

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

```bash
nvm install
nvm use
```

{% endstep %}

{% step %}

#### Install Dependencies

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

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

{% endstep %}

{% step %}

#### Configure Environment

Copy the example environment file:

```bash
cp .env.example .env
```

{% hint style="info" %}
The `docker-compose.yml` file contains sensible defaults for local development. Your `.env` file will override these when needed.
{% endhint %}

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

{% step %}

#### Build Frontend

Build the React frontend for development:

```bash
npm run build:frontend
```

Verify the build succeeded:

```bash
ls -la dist/frontend
```

You should see the built frontend files in the `dist/frontend` directory.
{% endstep %}

{% step %}

#### Start Development Environment

Launch all services:

```bash
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.
{% endstep %}
{% endstepper %}

### Troubleshooting

#### Need to restart?

If you need to start over from scratch:

```bash
# 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

{% hint style="success" %}
**✅ Success Check**: If you can access <http://localhost:5173> and see the FormSG interface, your local setup is working correctly!
{% endhint %}

#### Accessing email locally

FormSG uses [MailDev](https://github.com/maildev/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

{% hint style="info" %}
**For production**: Replace MockPass with your country's actual identity provider integration. See Component Customization for guidance.
{% endhint %}

#### Adding dependencies

Run `npm install` as per usual.

For backend dependencies, rebuild the containers:

```bash
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.