Deployment Guide

Learn how to deploy the Platform into your own Environments.


The 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. uses the Docker Container system as a mechanism to encapsulate each of our deployable products into deterministic and secure runtime environments. The products that 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:
Do not use the latest tag as this will pull in unreleased versions of the server
Deployable Product
This is the main API platform and portal interface for This enables the complete 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.
This is the PDF platform for, which includes all of the API interfaces for uploading existing PDF documents, to downloading submissions as PDF artifacts.
This is a special build of formio/pdf-server that enables the downloading of Submission PDF's using the USWDS template framework.

Deployment Licensing

Every deployment product of 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 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

The License Administrator can manage the license utilization by going to, 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.

Deployment Architecture

The 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 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 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.
Each environment can then consist of the following components.
A single 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
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.

Is there any Server to Server Communication?

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:
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.

Memory Requirements & Recommendations

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:
  • Using docker-compose: Set a NODE_OPTIONS variable with the value:
    - 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 your Environment

Installing Docker

Since 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 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 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.

Installing 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 requires a MongoDB compliant database, you will need to ensure that you have a valid database ready to go before installation of the on-premise software. If you are running a local installation of the 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 \
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

This is only required if you wish to run the PDF Server or also wish to upload files within your forms.
The 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 There are a number of File Services that work very well with the 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 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.

Installing Minio

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 \
--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 Platform.