🖥️Virtual Machine (Docker)

Deploy FormSG to a virtual machine for small-scale production use, staging environments, or pilot deployments. This guide uses Docker Compose on a single server to get FormSG running with minimal infrastructure complexity.

Overview

This deployment is ideal for:

• Pilot projects - Test FormSG with real users before full production

• Small organizations - Up to 1,000 form submissions per month

• Staging environments - Test customizations and integrations

• Air-gapped deployments - Isolated government networks

• Budget-conscious teams - Simple infrastructure with predictable costs

Prerequisites

• Cloud provider account (AWS, Azure, GCP) or physical server access

• Basic Linux command line knowledge

• SSH client on your local machine

• Domain name (optional but recommended)

Architecture Overview

This VM deployment runs FormSG components on a single server using docker containers, specific services can be seen in docker config here.

Deployment Steps

1

Create Virtual Machine

Cloud Provider Setup:

Choose your preferred cloud provider and create a new VM instance:

• AWS: EC2 → Launch Instance → Ubuntu 22.04 LTS

• Azure: Virtual Machines → Create → Ubuntu 22.04 LTS

• GCP: Compute Engine → VM instances → Create → Ubuntu 22.04 LTS

Recommended Specifications:

• CPU: 2 vCPUs (minimum 1 vCPU for testing)

• Memory: 4 GB RAM (minimum 2 GB)

• Storage: Few GBs, depending on need

• Network: Public IP address if external access needed

Instance Examples:

• AWS: t3.small or t3.medium (t2.micro for testing)

• Azure: Standard_B2s or Standard_B1ms (Standard_B1s for testing)

• GCP: e2-small or e2-medium (e2-micro for testing)

Security Group/Firewall Rules:

• SSH (port 22) from your IP address

• HTTP (port 80) from anywhere (if using domain)

• HTTPS (port 443) from anywhere (if using SSL)

• Custom port 5173 from anywhere (for direct access)

Security Note: Restrict SSH access to your IP address only. Consider using a VPN or bastion host for production deployments.

2

Connect to Your VM

SSH into your newly created virtual machine:

# Replace with your VM's public IP address
ssh ubuntu@YOUR_VM_IP_ADDRESS

# If using SSH key authentication (recommended)
ssh -i /path/to/your-key.pem ubuntu@YOUR_VM_IP_ADDRESS

First Time Setup:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install essential tools (adjust based on your VM setup)
sudo apt install -y curl wget git htop unzip

Additional tools: Depending on your VM setup, you may want to install other utilities like wget, htop, unzip, nano, or vim. Install what you need for your environment.

3

Install Docker and Docker Compose

This deployment path requires Docker and Docker Compose to run. Install them using your preferred method:

Option 1: Official Docker Installation (Recommended)

Follow the official Docker installation guide for Ubuntu:

• Visit: https://docs.docker.com/engine/install/ubuntu/

• Ensure you install Docker Compose plugin

Option 2: Quick Installation via Convenience Script

# Download and run Docker's convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose plugin
sudo apt-get update
sudo apt-get install docker-compose-plugin

Option 3: Package Manager Installation

# Install Docker from Ubuntu repositories (may be older version)
sudo apt update
sudo apt install docker.io docker-compose-v2

Post-Installation Setup:

# Add your user to docker group (avoids using sudo)
sudo usermod -aG docker $USER

# Apply group changes
newgrp docker

# Verify installation
docker --version
docker compose version
docker run hello-world

Note: You may need to log out and back in for group changes to take effect. The convenience script (Option 2) is often the easiest for most usecase.

4

Clone FormSG Repository

Get the FormSG source code:

# Clone FormSG repository
git clone https://github.com/opengovsg/FormSG.git
cd FormSG

# Install Node.js (using NodeSource repository)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify Node.js version
node --version  # Should show v22.x.x

5

Configure Environment

Set up FormSG configuration for your VM:

# Copy example environment file
cp .env.example .env

# Edit environment file
nano .env

Essential Configuration Changes:

Update these variables in your .env file:

# Email Configuration (required for OTP login)
# Option 1: Use a simple SMTP service
SES_HOST=smtp.gmail.com
SES_PORT=587
[email protected]
SES_PASS=your-app-password
[email protected]

# Option 2: Use your organization's SMTP
SES_HOST=mail.yourorg.gov
SES_PORT=587
SES_USER=formsg-service
SES_PASS=your-smtp-password
[email protected]


# Database (MongoDB will run in Docker)
DB_HOST=mongodb://mongo:27017/formsg

6

Install Dependencies and Build

Install FormSG dependencies:

# Install npm packages
npm install && npm --prefix serverless/virus-scanner install

# Build frontend for production
npm run build:frontend

# Verify build completed
ls -la dist/frontend

This step may take 5-10 minutes depending on your VM's specs and network speed.

7

Start FormSG Services

You have two options for starting FormSG:

Option 1: All-in-One (Recommended)

# Starts both frontend and backend services (via docker) together
npm run dev

This handles both the frontend build and Docker services automatically.

Option 2: Backend Only

# Start backend services only
docker compose up -d

# Then start frontend separately (in another terminal/tmux ession)
npm run dev:frontend

Use this if you want more control over individual services.

Services Starting:

• MongoDB: Database server

• MailDev: Email testing

• FormSG Backend: API server

• FormSG Frontend: Web interface (port 5173)

Recommended: Use npm run dev for simplicity. It handles everything you need for a VM deployment.

Accessing Your FormSG Instance

Web Interface

Open your browser and navigate to:

• Main Application: http://YOUR_VM_IP:5173

• Email Testing: http://YOUR_VM_IP:1080 (MailDev interface)

First Login

1. Go to the admin portal: http://YOUR_VM_IP:5173/login

2. Click "Login with Email"

3. Enter your email address

4. Check the MailDev interface (http://YOUR_VM_IP:1080) for the OTP code

5. Enter the OTP to complete login

Scaling

This VM deployment runs all FormSG components on a single server, which limits scaling options. For high-traffic scenarios or high availability requirements, consider moving to a cloud-native deployment with multiple servers.

When to Move Beyond VM Deployment

Consider migrating to a more robust deployment when you experience:

• High traffic: >1,000 concurrent users or >10,000 daily submissions

• Availability requirements: Need 99.9% uptime or zero-downtime deployments

• Advanced integrations: Complex workflows requiring multiple services

---

🎉 Congratulations! You now have FormSG running on a virtual machine. This provides a solid foundation for small-scale production use while maintaining full control over your infrastructure.