Self-Hosted Deployment

Learn how to deploy the Form.io Platform into your own Environments.

Introduction

The Form.io platform can be entirely installed within a cloud environment, within your own on-premise data center, or on your local machine. The platform is very flexible and offers many options for how to architect and configure it. There are a number of products that can be deployed within your own environment that enable a Micro-service architecture by deploying each product in either its own separate environment or within the same server. Form.io utilizes the Docker Container system as a mechanism to encapsulate each of Form.io's deployable products into deterministic and secure runtime environments. The products that Form.io has to offer as separate deployments are as follows.

When deploying a server version, tag the API and PDF Servers with the version you intend to use:

formio/formio-enterprise@9.3.0

formio/pdf-server@5.6.0

Deployable Product	Description
formio/formio-enterprise	This is the main API platform and portal interface for Form.io. This enables the complete Form.io API as well as the Developer Portal to be utilized within a deployed environment. This deployment also includes the Form Manager and FormView products as well for managing forms from a non-developer interface as well as launching forms for use within your own domain.
formio/pdf-server	This is the PDF platform for form.io, which includes all of the API interfaces for uploading existing PDF documents, to downloading submissions as PDF artifacts.
formio/uswds-viewer	This is a special build of formio/pdf-server that enables the downloading of Submission PDF's using the USWDS template framework.

Deployment License

Every deployment product of Form.io must have a valid license in order to run within an environment. After acquiring a License, you can enable that license for your deployment by setting the LICENSE_KEY variable within the environment variables for that deployment. Licenses can easily be managed by logging into https://portal.form.io as a license manager for your environment. These can view the license information and enable and disable associated for the servers, stages, projects, and more. Your license will have a set number of utilizations for each of the licensed features and the License Manager can control which of the usages are active at any given time. To free up license usage, you can disable an active utilization and then enable another utilization, as long as the user has the correct permissions to do so. You may also contact your Customer Success Representative to add additional features and increase the number of utilizations for your license.

Please note that Form.io issues a variety of different licenses. Be sure to use the correct deployment license, and not a Developer or Premium Library license when configuring a deployment.

Contact [e-mail] for more information about acquiring a license key.

License Management

The License Managers can configure their license utilization by navigating to https://portal.form.io. From the main Portal page, click the License Management tab on the left-hand navigation bar or click on your username clicking on your username at the top right of the portal, and then License Management.

Here you can view your License and all of the available utilizations included within your license like the API and PDF Servers, Projects and Stages, or other Enterprise add-ons like Multi-Tenancy. The License Manager can enable or disable the utilizations as needed.

Click Here for more information about the License Management UI

Contact [e-mail] for more information about becoming a License Manager user.

Use the License Manager to enable or disable certain products within your environments.

Deployment Architecture

The Form.io platform can be set up in any environment that supports Docker Engine. The configuration can be as simple as running the container and pointing a DNS entry to it but most Enterprise Users build out a high-performance/high-available stack to host the Form.io solution.

Typically, the Form.io platform is deployed with a 3 Environment License. This specific license enables you to create a very common deployment structure where you will have the following configuration within your own private cloud or on-prem environments.

Best Practice: The First Environment set up during deployment must be the Environment where the Portal Application is enabled. This environment is most commonly a middle, non-production environment as seen below.

Each environment can then consist of the following components.

A single Form.io environment

Since the Production environment differs slightly between the Dev Environment and Test / Authoring environment (where the Developer Portal is enabled), we will describe each of the deployment configurations based on the following definitions.

Environment Type	Description
API Server	An environment where the Developer Portal is disabled making this environment strictly an API interface for applications.
Portal Application	An environment where the Developer Portal is enabled allowing form builders to build and manage forms from the same domain as the API's for that environment.

While Docker is the recommended runtime environment for our Self-Hosted deployments, we also support Node.js environment where our platform runs entirely within the Node.js runtime. If this option is chosen, it should be noted that it is up to your organization to ensure all the dependencies are installed and up to date. This option is currently only available for the formio-enterprise product.

Contact [e-mail] for more information about using the Node.js deployment

Is there any Server to Server Communication?

No! The portal application is an application that is in the browser and communicates via API to the various environments through Stages within a Project.

Because the Portal Application lives in the browser, through API communication you can migrate forms and resources between Environments, all of which have a separate DB connection. There is no server-environment-to-server environment communication. The portal application communicates via API to the various environments through Stages within a Project. Because of this capability, a singular Project serves the SDLC from Dev to Stage to Prod as each of the stages has separate API endpoints, in separate environments as needed.

Click Here for more information

Memory Requirements & Recommendations

The minimum memory recommended is at least 8GB of RAM for the server to ensure stable and correct workflow. By default, the maximum size of Memory Usage sets as 4GB (4096 MB).

Here are commands to increase the maximum memory size for the server:

• Using Docker: Set a NODE_OPTIONS variable with the value:

  --max-old-space-size=8192

• Using docker-compose: Set a NODE_OPTIONS variable with the value:

  environment:
      - NODE_OPTIONS=--max-old-space-size=8192

• Using formio-enterprise Node.js app: Run the app with this option:

  node --max-old-space-size=8192 main.js

  Instead of 8192, you can set any size that you need in megabytes.

Preparing the Environment

Before deploying the container, first ensure the environment is ready for the deployment. Below are some recommended platforms and software to do so.

Docker

Docker Desktop offers an interface to build and run the containerized platform of Form.io. Since Form.io uses Docker as the runtime environment for all installations of the platform, it is recommended that the deployment environment has Docker installed.

In order to install Docker, please follow the instructions provided in the Get Docker guides. Docker may be installed locally, or use a Cloud Hosting provider that supports Docker containers within the instances. Some of the most common Cloud Hosting providers that are known to support Form.io deployments are as follows.

• Amazon AWS
• Microsoft Azure
• Google Cloud

Create the Docker Network

Once Docker is installed and ready to go, open the Docker Desktop application.

Next, create a network for all the containers to operate by running the following command from the terminal:

docker network create formio

The network call mentioned is typically only required when constructing deployment files to run Form.io. The docker-compose files found with the Local Deployment guide as well as the Cloud Hosting providers handle the network configurations automatically.

Now that the Docker environment is ready, establish a MongoDB database.

MongoDB

This step is only required when running a local installation. To use a managed database through services like MongoDB Atlas, Azure Cosmos DB, or Amazon DocumentDB then you should already have a database connection string and this step can be skipped.

Since Form.io requires a MongoDB-compatible database, ensure that a valid database is ready to go before the installation of the Form.io Self-Hosted software.

When running a local installation of the Form.io platform most users prefer to use the MongoDB Community Edition running on a local machine. While there are native installations available for MongoDB Community Edition found in the MongoDB Installation Guide it is probably easiest to install the MongoDB Docker container.

Installing MongoDB locally with Docker

Refer to the following process to deploy MongoDB via Docker container.

1. Creating a directory on the local machine in which to "mount" the database. On a Unix-based OS, the terminal command will be similar to the following:

mkdir ~/opt/mongodb

1. Deploy a local MongoDB container using the following command:

docker run -itd  \
  --name formio-mongo \
  --network formio \
  --volume ~/opt/mongodb:/data/db \
  --restart unless-stopped \
  mongo

Make sure to replace ~/opt/mongodb with the absolute path of the directory on the local machine used to store the databases.

Installing a File Server

A File Server is required if you wish to upload files within your forms or utilize the PDF Server within your environment

The Form.io platform commonly will use a File Server or Files Service to upload files from forms as well as upload PDFs utilized by the PDF Server. For this reason, a configured File Server is required before installing Form.io.

There are a number of File Services that work very well with the Form.io platform including Amazon S3 and Azure Blob Storage. Google Drive can also be used as a File Storage provider for the File Upload Component only

If you do not wish to use any of these services, OR if you wish to run the Form.io platform locally, then a popular alternative is to use the Minio File Service which is an Open Source file system alternative detailed below. It can also be easily deployed into a local environment as follows.

Minio

Minio is an open-source distributed object storage server written in Go, designed for Private Cloud infrastructure providing AWS S3 storage functionality. This server is best suited for storing unstructured data and files such as photos and videos within your local environment. You can read more about Minio within the Local Deployment guide linked here.