FormSG Documentation

FormSG is a feature-rich form builder designed for secure citizen data collection. Self-hosting FormSG allows organizations to:

• Maintain complete data sovereignty within their own jurisdiction.
• Integrate with existing systems and identity providers.
• Meet specific compliance requirements for regulatory environments.
• Reduce vendor lock-in while maintaining operational control.

Note: This repository contains self-hosting documentation. For end-user guides on how to create and manage forms, visit https://guide.form.gov.sg/.

The Monitoring and Logging Pattern provides visibility into application performance and security. It requires:

• Application performance monitoring (APM).
• Security event logging and alerting.
• Infrastructure metrics collection.
• Centralized log aggregation.

Conceptual Configuration Example:

monitoring:
  metrics:
    - container_cpu_usage
    - container_memory_usage
    - application_response_time
    - database_connections
    - failed_authentications
  
  alerts:
    - high_cpu: "> 80% for 5 minutes"
    - high_error_rate: "> 5% for 2 minutes"
    - failed_health_checks: "> 2 in 1 minute"
  
  logs:
    - application_logs
    - access_logs  
    - security_events
    - audit_trail

The Container Service Pattern runs the FormSG application with auto-scaling and health monitoring. Key requirements include:

• A container with health checks.
• Auto-scaling based on CPU/memory utilization.
• Environment variables sourced from a secure configuration store.
• A load balancer for high availability.

Conceptual Configuration Example:

service_name: formsg
container_image: your-registry/formsg:latest
port: 5000
health_check_path: /api/v3/admin/forms
environment_variables:
  NODE_ENV: production
  DB_HOST: ${database_connection_string}
  SESSION_SECRET: ${secure_session_secret}
scaling:
  min_instances: 2
  max_instances: 10
  cpu_threshold: 70%

FormSG is architected for AWS, but it is cloud-agnostic in theory. When deploying to other clouds (GCP, Azure, or On-Premise), do not look for direct product replacements. Instead, map FormSG's requirements to standard infrastructure patterns:

FormSG allows setting notification banners via environment variables. You can specify the banner type using prefixes: info:, warn:, or error:. If no prefix is provided, it defaults to info:.

Banner Precedence for Public Form Routes: SITE_BANNER_CONTENT > IS_GENERAL_MAINTENANCE > IS_SP_MAINTENANCE > IS_CP_MAINTENANCE

Banner Precedence for Private Form Routes: SITE_BANNER_CONTENT > ADMIN_BANNER_CONTENT

Banner Precedence for Login Page: SITE_BANNER_CONTENT > IS_LOGIN_BANNER

SITE_BANNER_CONTENT=info:This is an info banner. You can also add links in the text like https://example.com. There is also a dismiss button to the right of the text.

FormSG's design decisions impact how you should manage and customize your deployment. Understanding these helps maintain a secure posture:

The Load Balancing and Networking Pattern securely exposes FormSG while protecting backend services. It requires:

• TLS termination with approved certificates.
• A Web Application Firewall (WAF).
• Network segmentation between public and private resources.
• DDoS protection and rate limiting.

Conceptual Configuration Example:

load_balancer:
  type: application_load_balancer
  listeners:
    - port: 443
      protocol: HTTPS
      certificate: your-gov-domain-cert
    - port: 80
      protocol: HTTP
      action: redirect_to_https

networking:
  public_subnets:
    - load_balancer
  private_subnets:
    - application_containers
    - database
  security_groups:
    lb_to_app: port_5000_only
    app_to_db: port_27017_only

Self-hosting FormSG requires specific technical skills. While not a hard requirement for day one, teams should aim to acquire or possess the following capabilities:

Minimum Technical Skills Needed:

• Basic Linux server administration
• Docker or container orchestration experience
• Environment variable and secrets management
• Working with Node.js applications
• Understanding of web application security

Team Capability Models:

• Small teams (1-2 people): Full-stack developers capable of learning DevOps.
• Medium teams (2-4 people): A mix of development and infrastructure skills.
• Large teams (5+ people): Specialized roles in DevOps, development, and security.

The script attempts to identify four primary languages used in Singapore. Because detecting language is complex (especially when multiple languages appear in the same text block), it uses different strategies:

• Chinese and Tamil: Identified using dedicated Unicode character ranges.
• English and Malay: Identified using a heuristic approach that looks for frequently occurring words specific to these languages (since both use Latin characters).
• Unknown: Any text that does not match the specific language patterns is categorized as unknown. This often occurs when English forms contain non-standard or "funky" words.

The script generates reports for two specific categories:

1. Forms where multiple languages are detected.
2. Forms where only one language is detected, and that language is not English.