🖥️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:

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.

PreviousDeploymentNextAWS

Last updated

Was this helpful?