Deployment Configurations

Recommended Specifications

The form.io platform can be set up in any environment that supports Docker Engine. The configuration can be as simple as running our container and pointing a dns entry to it but most of our customers build out a high performance/high available stack. The following information should provide guidelines on how to set that up.

Server requirements

Our architecture is very performant, even on smaller servers. Because our servers are stateless, you can easily run multiple of them in parallel behind a load balancer to increase capacity during times of higher load. Still, we recommend running the following sized servers. These have been stress tested to hundreds of concurrent users without impact.

Requirement	Available Options
Server manufacturer	AWS Azure Google Cloud
Processor make	Intel Xeon Intel Xeon E5 AMD Opteron or compatible
Processor instruction set	X86, AVX2 (AVX is also supported)
Processor architecture	64-bit
Processor speed	1.0 GHz or faster
No. of physical cores	1
Processor cache	2MB or greater
Total RAM	3GB or greater (Example AWS m3.medium)
Hardware allocation	The host server must not be over-committed in terms of either RAM or CPU to other processes besides the Form.io API Server. The Form.io API Server must have dedicated access to its own RAM and CPU cores.
Application Storage	4GB or greater (Example AWS m3.medium)
Blob Storage	128GB
GPU	N/A
Network	> 1 Gigabit
Operating System	Ubuntu > v18.0 Debian > v8.0 Alpine Linux > v3.5.0

The PDF server should have double the amount of RAM than the API server due to creating PDFs within memory. So we would recommend 8 GB RAM for PDF server.

Deployment Diagram

TLS/SSL Setup (https)

What is SSL?

TLS/SSL enables encrypted communication at the container level. This ensures all traffic to and from the running Docker container(s) is encrypted.

Why would I need TLS/SSL?

TLS/SSL is needed if you require a strict communication standard requiring all network traffic to be run through TLS/SSL encryption.

In order to enable TLS/SSL (https) for your environment, there are several options for how to do so. Most Load Balancers in the cloud contain HTTPS listeners that can be configured with proper SSL Certificates. These can then point to the listening ports on the form.io server.

If you are not using a load balancer that has SSL support, it's encouraged to use NGINX to proxy the requests to your server and install your SSL Certificates.

Click here for more info on NGINX setup

First, you will need certificates. You can either generate your own, use LetsEncrypt, or purchase an SSL certificate. Once you have a certificate you can configure NGINX.

A sample configuration that proxies the server, listens on port 443 and uses your SSL Certificates

server {
  listen 443 ssl;
  server_name  ~^(www\.)?(.+)$;
  client_max_body_size 20M;
  ssl_certificate      /usr/local/etc/nginx/nginx.crt;
  ssl_certificate_key  /usr/local/etc/nginx/nginx.key;
 
  location / {
    proxy_set_header    Host $host;
    proxy_set_header    X-Real-IP $remote_addr;
    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header    X-Forwarded-Proto $scheme;
    proxy_pass          http://localhost:3000;
    proxy_read_timeout  90;
    proxy_redirect      http://localhost:3000 https://$host;
  }
}

If you also have a Minio + PDF Server running on this server, then you will also want to provide them within subdirectories like the following.

For this configuration to work with Minio, you will need to create a subdomain @ http://minio.yourserver.com that points to this server. Minio does not support being hosted outside of the root domain.

server {
  listen 443 ssl;
  server_name  ~^(www\.)?(.+)$;
  client_max_body_size 20M;
  ssl_certificate      /usr/local/etc/nginx/nginx.crt;
  ssl_certificate_key  /usr/local/etc/nginx/nginx.key;
 
  location / {
    proxy_set_header    Host $host;
    proxy_set_header    X-Real-IP $remote_addr;
    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header    X-Forwarded-Proto $scheme;
    proxy_pass          http://localhost:3000;
    proxy_read_timeout  90;
    proxy_redirect      http://localhost:3000 https://$host;
  }

  location /files/ {
    rewrite ^/files/(.*)$ /$1 break;
    proxy_set_header    Host $host;
    proxy_set_header    X-Real-IP $remote_addr;
    proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header    X-Forwarded-Proto $scheme;
    proxy_pass          http://localhost:4005;
    proxy_read_timeout  90;
    proxy_redirect      http://localhost:4005 https://$host;
  }
}

server {
   listen 443 ssl;
   server_name  ~^minio.(.+)$;
   client_max_body_size 20M;
   ssl_certificate      /usr/local/etc/nginx/nginx.crt;
   ssl_certificate_key  /usr/local/etc/nginx/nginx.key;
 
   location / {
     proxy_buffering off;
     proxy_set_header Host $http_host;
     proxy_pass http://localhost:9000;
   }
}

Enabling an additional TLS/SSL Layer on top of Docker Containers

In the extremely rare case that terminating TLS/SSL at the load balancer or reverse proxy does not suffice, and an additional container to container TLS/SSL layer is required, a TLS/SSL layer can be configured in your Docker Containers to enable encrypted traffic between them.

This configuration is rarely necessary. Do not use unless absolutely required.

Enabling a TLS/SSL Layer on top of Docker Container encrypts traffic from the container all the way to the Form.io applications and requires additional configuration. The setup requires an SSL certificate. A CA Signed Certificate or self-signed certificate can be used.

To enable SSL on top of Docker container, the following Environment variables must be added to the deployment:

ENABLE_SSL=true
SSL_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAs72aa5FKcRmLMJnVx/4AWI1PNcvJOMAAbSc/NXJAt5Gs9QZI\nw0I..."
SSL_CERT="-----BEGIN CERTIFICATE-----\nMIIDcTCCAlkCFHox4bsG4jGVtB9WvObnL8LnToGeMA0GCSqGSIb3DQEBCwUAMHUx\nCzAJ..."

API Server TLS/SSL Environment Variables

Variable	Description	Example
ENABLE_SSL	A boolean value indicating whether you wish for the API server be able to terminate TLS/SSL-encrypted traffic	ENABLE_SSL=true
SSL_KEY	The SSL certificate's private key value (not its path in the filesystem!)	SSL_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAs72aa5FKcRmLMJnVx/4AWI1PNcvJOMAAbSc/NXJAt5Gs9QZI\nw0I..."
SSL_CERT	The SSL certificate's value (not its path in the filesystem!)	SSL_CERT="-----BEGIN CERTIFICATE-----\nMIIDcTCCAlkCFHox4bsG4jGVtB9WvObnL8LnToGeMA0GCSqGSIb3DQEBCwUAMHUx\nCzAJ..."

PDF Server TLS/SSL Environment Variables

Variable	Description	Example
ENABLE_SSL	A boolean value indicating whether you wish for the PDF server to terminate TLS/SSL-encrypted traffic	ENABLE_SSL=true
SSL_KEY	The SSL certificate's private key value (not its path in the filesystem!)	SSL_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAs72aa5FKcRmLMJnVx/4AWI1PNcvJOMAAbSc/NXJAt5Gs9QZI\nw0I..."
SSL_CERT	The SSL certificate's value (not its path in the filesystem!)	SSL_CERT="-----BEGIN CERTIFICATE-----\nMIIDcTCCAlkCFHox4bsG4jGVtB9WvObnL8LnToGeMA0GCSqGSIb3DQEBCwUAMHUx\nCzAJ..."

Pay special attention to the settings for the SSL_KEY, SSL_CERT environment variables:

-new lines in the corresponding file should be set to '\n'

-double quotes should be used

For a walkthrough of how to set up this type of environment in AWS, please see the that has been configured with TLS/SSL between containers, please see the Form.io/AWS Elastic Beanstalk E2E Encrypted Environment tutorial.

DNS Configuration

DNS Setup

In order to access your form.io server, a domain name needs to be set up for it and pointed to the server or load balancer. This can be a subdomain of another domain, however, the Form.io subdomain will NOT work with our server so use any other subdomain such as forms.

As an example, you can set “forms-dev” to point to the portal-enabled environment so you would go to https://forms-dev.mydomain.com to access the server.

There are two options for configuring project DNS for your docker server. You can run it using subdomains or run on a single subdomain and have projects as subdirectories of that domain.

Subdirectories

When using Subdirectories to refer to projects, simply set up a single domain and point it to the server. All projects will become subdirectories of that domain instead of subdomains. Be sure to select “Subdirectory” from the Project Path Type in the environment switcher.

For example: https://forms-dev.mydomain.com would result in the following project paths:

https://forms-dev.mydomain.com/myproject1 https://forms-dev.mydomain.com/myproject2

If using subdirectories, skip the Subdomains section.

Subdomains

When using subdomains, the server DNS must have the following three domains set up and an additional one per project OR have a wildcard subdomain entry in the DNS server.

Every deployment needs the following 3 subdomains to function.

HostName	Description
api.yourdomain.com	This subdomain points to the core API of the Form.io platform.
formio.yourdomain.com	This points to the Main Form.io project which is required to login and manage your deployment.
[YOURPROJECT].yourdomain.com	This points to the project within the deployment, which is your applications Form.io project.

PDF

If you are using a pdf server, you will also need to point a subdomain at your pdf server. For example, pdf-dev.myserver.com can point to the server or load balancer. This will make the server available so that it can serve up the converted PDFs that are the background for Web PDFs in the form.io platform. If you are NOT using Web PDFs and only want to generate PDFs of submissions you do NOT need to make the PDF server available on the internet and only need to have it available to the Form.io Server.

Files

Files are frequently uploaded to the Blob Storage mechanism of your hosting provider. It is not required to have a clean URL like files-dev.myserver.com that points to the blob storage but you may set one up. You can use a raw blob storage URL as well.

Remote Environments

Multiple Environments

When deploying the form.io platform, it is possible to enable the portal application as well. This includes form manager, FormView Pro, and Tenant Manager if applicable. This application is the primary interface into your environments in your On-Premise servers. It is important to understand how to set this up correctly.

You should pick only one of your environments to be the Portal environment. This is typically the “Dev” environment since it will be the place all your developers will use to log in and manage the forms and data. Typically the Pre-prod and Prod environments are partitioned off and only available to certain employees responsible for deployments.

There are a few differences between a Portal environment and a Remote environment.

Portal Environment

1. The environment variable PORTAL_ENABLED=true has been set.

2. The Portal application is served from the root of the environment.

3. A Portal Base project is automatically created within the database. This project is NOT counted against your license. It is where all of the users and teams will be stored for the Portal application. You should not add additional forms or resources in this project.

4. An admin user is created in the Portal Base project. You can set the email and password for this in the environment variables ADMIN_EMAIL and ADMIN_PASSWORD. This can only be set the first time the server is started with PORTAL_ENABLED set. Once it has been run, the environment variables can be removed and any subsequent changes to the admin user can be done by going to the Portal Base project and the User resource.

Remote Environment

1. The environment variable PORTAL_SECRET has been set to a random secure secret.

2. There is NO application served from the root of the environment. By default, it will respond with [].

3. You will connect a project or stage to this environment by using the “On Premise Environment” option in the project settings. You will need to know the PORTAL_SECRET for the remote environment when setting it up.

4. You can set up multiple remote environments and use the portal environment to connect projects and stages to different remote environments.

Moving stages to remote environments

Once you have your Portal and Remote environments set up, create a project in Portal environment and create stages within the project that will go on the remote environments. Next, go to a stage, click Settings and navigate to “On Premise Environment”. Enter the URL for the remote environment and the portal secret from the remote environment. Leave the Project Path Type as “Subdirectories” and click “Continue”. This should connect to the remote environment. Select “New Stage” and then press “Connect Stage”. You can repeat this with other stages and other remote environments.