Deployment Guide
Learn how to deploy the Form.io Platform into your own Environments.
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. 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 uses the Docker Container system as a mechanism to encapsulate each of our 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/[email protected]formio/[email protected]Do not use the latest tag as this will pull in unreleased versions of the server
formio/formio-enterprise:latestDeployable 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. |
Every deployment product of Form.io must have a valid license in order to run in a production environment. When provided with a license, you can enable that license on a deployment by setting the LICENSE_KEY variable in environment variables for that deployment. Licenses can easily be managed by logging into https://portal.form.io 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.
The License Administrator can manage the Form.io license utilization by going to https://portal.form.io, clicking on your username in the top right of the portal, and then "License Management".
You can then view the API servers, PDF Servers, and Projects associated with a Remotely Deployed License Key, to enable or disable the utilizations as needed. Each of the sections "API Servers", "PDF Servers", "Projects", etc. are clickable, which will give you a detailed list of the utilizations.
Use the License Manager to enable or disable certain products within your environments.
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 to host the Form.io solution.
While Docker is the preferred runtime environment for our On-Premise 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. For more information about using the Node.js deployment, please contact Support.
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 remote environment.
.png?alt=media&token=d101c5ac-069c-473e-9c9e-ae14ec5cab6e)
Each environment can then consist of the following components.
A single Form.io environment
Since the Production environment differs slightly between the Dev / Test and Authoring environments (where the Developer Portal is enabled on the non-production environments), we will describe each of the deployment configurations based on the following definitions.
Environment Type | Description |
API Environment | An environment where the Developer Portal is disabled making this environment strictly an API interface for applications. |
Portal Environment | 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. |
No! The portal application is an application that is in the browser which communicates via API to the various environments through Stages within a Project. Please read more here: https://help.form.io/userguide/stages#isolated-environments
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 UAT to Prod as each of the stages has separate API endpoints, in separate environments as needed.
We recommend using at least 8GB of RAM for the server to ensure stable and correct work.
By default, the maximum size of Memory Usage sets as 4GB (4096 MB).
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.jsInstead of 8192, you can set any size that you need in megabytes.
Since Form.io uses Docker as the runtime environment for all of its on-premise products, you will first need to ensure that your Environment has Docker installed. In order to install Docker, please follow the instructions provided in the Get Docker guides. You can either install Docker locally, or you can also use many Cloud Hosting providers that support Docker containers within their instances. Some of the most common Cloud Hosting providers that are known to support Form.io deployments are as follows.
Once Docker is installed and ready to go, you first create a network for all your containers to run within.
docker network create formio
This is usually only required if you are running the Form.io containers within a local environment. Many of the cloud hosting providers handle the network configurations for you.
Now that your Docker environment is ready, you will next need to acquire a MongoDB database.
This step is only required if you are running a local installation. If you have 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 compliant database, you will need to ensure that you have a valid database ready to go before installation of the Form.io on-premise software. If you are running a local installation of the Form.io platform, then you will most likely want to use the MongoDB Community Edition on your local machine so that you can easily develop applications within your own local environments. While there are native installations available for MongoDB Community Edition found at MongoDB Installation Guide it is probably easiest to install the MongoDB Docker container.
This can be done by first creating a directory in which to "mount" the database to your local machine. This can be done by first creating a directory on your local machine to contain the database, which for Unix based OS can be done in the terminal with the following command.
mkdir ~/opt/mongodb
Once this directory is created, you can then 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
You will want to make sure that you replace
~/opt/mongodb with the absolute path of the directory on your local machine you wish to store your databases.This is only required if you wish to run the PDF Server or also wish to upload files within your forms.
The Form.io platform commonly will use a File Server or Files Service to upload files from forms as well as upload PDF's used by the PDF Server. For this reason, it is a very common pre-requisite to have a file server configured and ready to go 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. ( NOTE: Google Drive can also be used as a File Storage provider, but 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. It can also be easily deployed into a local environment as follows.
To install Minio locally, you must first create a few folders within your local file system to store the files uploaded through the Minio platform. This can be done either through a file browser, or if you are on a Unix based system with the following commands.
mkdir ~/minio/data
mkdir ~/minio/config
Once these directories are created, you can then launch Minio locally with the following command.
docker run -itd \
-e "MINIO_ACCESS_KEY=CHANGEME" \
-e "MINIO_SECRET_KEY=CHANGEME" \
--network formio \
--name formio-minio \
--restart unless-stopped \
-p 9000:9000 \
-p 9001:9001 \
-v ~/minio/data:/data \
-v ~/minio/config:/root/.minio \
minio/minio server /data --console-address ":9001"
If you wish for a more secure deployment, then you can exclude the environment variables for
MINIO_ACCESS_KEY and MINIO_SECRET_KEY as follows.docker run -itd \
--network formio \
--name formio-minio \
--restart unless-stopped \
-p 9000:9000 \
-p 9001:9001 \
-v ~/minio/data:/data \
-v ~/minio/config:/root/.minio \
minio/minio server /data --console-address ":9001"
You can then determine these keys by running the following docker command.
docker logs formio-minio
Make sure to take note of these keys for later configurations. You are now ready to deploy the Form.io Platform.
Last modified 10d ago