On Premise

Introduction

The form.io platform can be entirely installed on premise within a cloud environment or within your own data center. The platform is very flexible and offers many options for how to architect and configure it. Please contact sales@form.io at any time to discuss your specific needs in architecting a solution.

At a high level the form.io platform consists of two docker containers that contain node.js programs that serve an API and Single Page Application (SPA).

Licensing

Starting with the 7.x version of formio-enterprise and the 3.x version of pdf-server, our licensing has been simplified and standardized to make it easier to configure and deploy the form.io platform. If you have previous version of the license, please contact sales@form.io and request a new license key. You can tell if you have a new license key as it is 16 characters long instead of the old one which was over 100 characters long.

Server instances must have access to https://license.form.io in order to check the license. Be sure that you have opened that domain in your private VPC.

When provided with a license, you can use this license on both the Formio server and the PDF server. On both servers, set the LICENSE_KEY variable in environment variables. This will tell the server which license to associate the server with. You can manage your license utilizations by going to https://portal.form.io and loggin in as one of the license users. These users can view the license information and enable and disable associated servers and projects. Your license will have a maximum number of utilizations for each of the licensed features and you can control which of the usages are active at any given time. To free up another usage, you can disable a currently enabled item and then create a new one. You may also contact your sales representative to add additional features and increase the numbers on your license.

License Management Page

Please note that license management is only available on https://portal.form.io and your user account must be associated with the license.

Architecture

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. In addition, since 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 hundres of concurrent users without impact.

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

Deployment Diagram

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 formio 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 enviromnent so you would go to https://forms-dev.mydomain.com to access the serve.

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.

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 of 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 environement 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. Then go to a stage, go to settings and “On Premise Environmnent”. Enter the URL for remote environment and the portal secret from the remote environment. Leave 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.

SSL Setup (https)

In order to enable 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, you can use NGINX to proxy the requests to your server and install your SSL Certificates. 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.

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;
   }
}

Note, 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 outsiide of the root domain.