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.0.0
formio/pdf-server@5.5.2
The latest tag will always point to the latest stable release. Any release candidates will be tagged as rc.
formio/formio-enterprise:latest
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.
Contact support@form.io 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 support@form.io for more information about becoming a License Manager user.
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.
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 support@form.io 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:
Using docker-compose: Set a NODE_OPTIONS variable with the value:
Using formio-enterprise Node.js app: Run the app with this option:
Instead of 8192, you can set any size that you need in megabytes.
Preparing your Environment
Before deploying the container, we need to first ensure the environment is ready for the deployment. Below are some recommended platforms and software to help you do so.
Docker
Docker Desktop offers a seamless interface that allows you 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 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 open the Docker Desktop application. Next, create a network for all your containers to run by running the following command. in your Terminal.
The network call mentioned is typically only required if you are constructing your own 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 for you.
Now that your Docker environment is ready, you will next need to acquire a MongoDB database.
MongoDB
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-compatible database, you will need to ensure that you have a valid database ready to go before the installation of the Form.io Self-Hosted 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.
Once this directory is created, you can then deploy a local MongoDB container using the following command.
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.
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.
Last updated
