LogoLogo
Getting StartedDevelopersDeployment GuideGet Help
  • Quick Links
  • Welcome to Form.io
    • Getting Started With Form.io
    • Launch a Form
    • Overview of Form.io
  • Developer Tool Ecosystem
    • PDF Solution
    • Enterprise Form Builder
    • Form View Pro
    • The Security Module
    • Accessibility Compliance Module
    • Developer License
    • SQL Connector - Deprecated
    • Integration Libraries
    • Form.io CLI Tool
  • User Guide
    • Introduction
    • Form.io Developer Portal
    • Teams
    • Projects
      • Project UI
      • Project Settings
      • Stages
      • Multi-Tenancy
    • Resources
      • ResourceJS
    • Forms
      • Form Creation
      • Form Types
      • PDF Forms
      • Embedding a Form
      • Form Revisions
      • Form Settings
    • Form Building
      • Form Builder UI
      • Form Components
        • Component Settings
        • Basic Components
          • Resource as Select Component Data Source
        • Advanced Components
        • Layout Components
        • Data Components
        • Premium Components
          • Nested Forms
        • Custom Components
      • Logic & Conditions
      • Existing Resource Fields
      • Actions
    • Submissions
      • Accessing Submissions
      • Importing Submissions
    • Form.io eSignature - Coming Soon
    • Form.io Reporting Module
    • PDF Template Designer
    • Form View Pro
    • Form Manager
    • Enterprise Form Builder Module
      • Installation
      • User Guide
  • Developer Guide
    • Introduction
      • Application Development
      • API Documentation
    • Form Development
      • Form Renderer
      • Form Builder
      • Form Embedding
      • Form Evaluations
      • Form Templates
      • Custom Components
      • Translations
    • JavaScript Development
      • JavaScript SDK
      • JavaScript Frameworks
      • JavaScript Utilities
    • Authentication and Authorization
      • SAML
      • OAuth
      • LDAP
      • Resource Based Authentication
      • Email Authentication
      • Two-Factor Authentication
    • Roles and Permissions
      • Field Match-Based Access
      • Field-Based Resource Access
      • Group Permissions
    • Integrations
      • Email Integrations
      • File Storage
      • Google Developer Console
      • eSign Integrations
      • Relational Databases
    • Modules
    • Fetch Plugin API
    • CSS Frameworks
    • Offline Mode
    • Audit Logging
  • Deployments
    • Self-Hosted Deployment
      • Local Deployment
        • Local File Storage
      • Kubernetes
      • Cloud Deployment
        • AWS Deployment
          • AWS Lambda
          • Form.io/AWS Elastic Beanstalk End-To-End Encrypted Deployment
        • Azure Deployment
          • Azure App Service
            • Azure MSSQL Connector - Deprecated
          • Azure Virtual Machine
          • Azure Kubernetes Service
          • Set up the DB
        • GCP Deployment
          • GCP Cloud Run
      • On-Premise Deployment
      • Enterprise Server
      • PDF Server
    • Deployment Configurations
      • DNS Configuration
      • Load Balancer Configuration
    • Licenses
      • License Management
      • Library Licenses
    • Portal Base Project
      • Portal SSO
      • Portal Translations
    • Maintenance and Migration
      • Changes to Premium Libraries
  • FAQ
    • FAQ
    • Tutorials & Workflows
      • Password Reset
      • Dynamic Select Filtering
      • Approval Workflow
      • SSO Email Token
      • Embedding A Video
      • Data Source Validation
      • Select Data Source Options
      • Nested Form Workflows
        • Nested Wizard Forms
      • Save as Draft
      • Role-Based Conditions
      • Custom Component
      • Dynamic Radio and Select Box Values
      • Override CKEDITOR
    • Errors
    • Examples
    • License Utilization Checks
    • Glossary of Key Concepts
  • Contact Us
Powered by GitBook
On this page
  • Environment Variables
  • Database Connection String
  • Form.io Enterprise API Server Environment
  • Portal Enabled Environment
  • Stand-Alone API Environment

Was this helpful?

  1. Deployments
  2. Self-Hosted Deployment

Enterprise Server

Deploying the primary Self-Hosted product of Form.io. The Enterprise Server.

PreviousOn-Premise DeploymentNextPDF Server

Last updated 3 months ago

Was this helpful?

We will start our deployment with the Form.io Enterprise Server, which can be found on Docker Hub at the following URL.

A Docker Compose can be found here to set up the API Server Container (formio-enterprise) only, without the PDF Server Container:

The Enterprise Server can be deployed as follows:

docker run -d \
  -e "LICENSE_KEY=abcdefghi1234567890" \
  ...
  ...
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  -p 3000:3000 \
  formio/formio-enterprise

Where the environment variables would be replaced with the following.

Environment Variables

Within the tabs below are all of the variables that are available for the formio/formio-enterprise deployments. Some of these variables are required to deploy the Enterprise servers while others are recommended.

It's recommended to change the Admin email and password to something secure before deploying.

Environment Variable

Description

Example

MONGO

The MongoDB connection string to connect to your remote database.

mongodb://<credentials>@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true

LICENSE_KEY

A valid license obtained from form.io.

abcdefghi1234567890

DB_SECRET

The database encryption secret

CHANGEME

PORTAL_ENABLED

Used if you wish to enable the portal in this environment making this a Portal Environment

true

ADMIN_EMAIL

If PORTAL_ENABLED is set to "true" this is used to determine the default root user email login

admin@example.com

ADMIN_PASS

If PORTAL_ENABLED is set to "true", this is used to determine the password of the default root user login

CHANGEME

PORTAL_SECRET

If PORTAL_ENABLED is not set (as in an API Environment), then this secret is used to connect another portal to this environment

CHANGEME

JWT_SECRET

The secret password for JWT token encryption.

CHANGEME

PDF_SERVER

The deployed PDF Server URL

http://pdf-server:4005

These variables are required to deploy within your environment.

Environment Variable

Description

Example

LICENSE_KEY

A valid license obtained from form.io.

abcdefghi1234567890

LICENSE (Legacy Server Only)

The license environment variable used for legacy 6.x server versions only.

A long JWT token

Environment Variable

Description

Example

DEBUG

Adding debugging messages to the server. Use ‘formio.’ for all Form.io messages and ‘.*’ for all debug messages.

MONGO

The MongoDB connection string to connect to your remote database.

mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true

MONGO_CA

The file path to a custom SSL certificate authority file. This is usually a file ending with ".pem"

/src/certs/rds-combined-ca-bundle.pem

MONGO_SSL_VALIDATE

Enables (true) or disables (false) the ssl domain validation when connecting to the database. This is useful when connecting to a database through an SSH proxy that requires a ssl certificate that validates domain names.

false

MONGO_CONFIG

Provides a way to pass custom MongoDB configurations into the MongoDB connection string. This should be a JSON string, and all the configurations are documented at https://mongoosejs.com/docs/connections.html#options

JWT_EXPIRE_TIME

Configures the expiration time for the JWT token that is generated for authentication. Value is in minutes, so 240 would be 4 hours.

240

ADMIN_KEY

An optional key that gives full access to the server including listing all projects. Send in a header with x-admin-key

[ADMIN KEY]

PORTAL_ENABLED

Used if you wish to enable the portal in this environment making this a Portal Environment

ADMIN_EMAIL

The default email of the super admin account. Only on initial startup when PORTAL_ENABLED is set to "true".

[email]

ADMIN_PASS

The default password of the super admin account. Only on initial startup when PORTAL_ENABLED is set to "true".

[password]

PORTAL_SECRET

The secret used to connect the portal to your environment

[PORTAL SECRET]

ONLY_PRIMARY_WRITE_ACCESS

Authenticated Form.io Users can no longer create a Project or Team within the deployed environment. The Create Project and Team buttons will no longer be visible to authenticated users within the Portal. Any attempt to create a project or team via API using the Authenticated role will result in an Unauthorized response

true

PDF_SERVER

This is the URL of the PDF server, which is set within the API server so that it can download Submission PDF’s pointed to the PDF Server

http://pdf-server:4005

DB_SECRET

The database encryption secret

[DB SECRET]

DB_SECRET_OLD

If you need to change the DB_SECRET, set the old value here and it will decrypt with the old and encrypt with the new the next time the server is started. Once changed, you can remove the DB_SECRET_OLD.

[OLD DB SECRET]

EMAIL_OVERRIDE

Provides a way to point all Email traffic to a server. Should not be used in Production.

{“transport”:”smtp”,”settings”:{“port”:2525,”host”:”smtp.mailtrap.io”,”auth”:{“user”:”23esdffd53ac”,”pass”:”324csdfsdf989a”}}}

JWT_SECRET

The secret password for JWT token encryption.

[TOKEN SECRET]

JWT_EXPIRE_TIME

The expiration for the JWT Tokens

240

MAX_BODY_SIZE

Sets the Maximum POST body size.

16mb

DOCKER_SECRETS

Enable the use of Docker Secrets

1

DOCKER_SECRETS_PATH

The path to the Docker Secrets folder

/run/secrets

PORTAL_SSO

Enables the portal to automatically authenticate with SSO through the Portal Base authentication provider configurations.

false

PORTAL_SSO_LOGOUT

The url to redirect the users when they click the logout button when you have Portal SSO enabled.

SSO_TEAMS

Allows you to authenticate into portal with an Authentication provider and map Group names to Form.io Teams. This is enabled by default when you have Portal SSO enabled.

false

BASE_URL

An accessible url of this server. This is necessary when attaching submission pdfs to an email in an Email Action.

HTTP_PROXY

HTTPS_PROXY

NO_PROXY

PORT

The port which the server should run on. Default 80

LICENSE_REMOTE

A boolean to determine if this environment is going to use an "offline" license, which is a special type of license that removes the requirement for a ping to https://license.form.io when starting the container.

true

DROPBOX_CLIENTID

If you are using Dropbox file uploads for your remote deployment, you will need to place your API client ID.

DROPBOX_CLIENTSECRET

If you are using Dropbox file uploads for your remote environment, you will need to place your API client secret.

SENDGRID_USERNAME

If you would like to provide a default SendGrid account for your deployment, then this is the account name in SendGrid to use.

SENDGRID_PASSWORD

If you would like to provide a default SendGrid account for your full deployment, then this is the SendGrid API Key.

ESIGN_PRIVATE_KEY

RSA2048 private key that will be used by default for form.io eSignature cryptographic operations

FORMIO_VM_TIMEOUT

Form.io uses a secure VM to execute custom logic

Define the maximum execution time (in milliseconds) for scripts running in a sandboxed virtual machine (VM) environment.

500

HSTS_MAX_AGE

The time, in seconds, that the browser should remember that a site is only to be accessed using HTTPS. Set to 0 to remove HSTS header

31536000

HSTS_INCLUDE_SUB_DOMAINS

If this optional parameter is specified, this rule applies to all of the site's subdomains as well.

true

HSTS_PRELOAD

true

Using Docker Secrets As Environment Variables

Using Environment Variables with Node.js

For the Node.js deployments, we use a Node.js utility called dotenv to configure the environment variables of the running node application. This can be configured by creating a .env file at the root of the Node.js application, that is similar to the following.

LICENSE_KEY=abcdefghijk1234567890
MONGO=mongodb://admin:blahblah@aws-us-east-1-portal.25.dblayer.com:234234,aws-us-east-1-portal.26.dblayer.com:234234/formio?ssl=true
PORTAL_SECRET=CHANGEME
DB_SECRET=CHANGEME
JWT_SECRET=CHANGEME

Database Connection String

When connecting to your database, it is important that you provide the name of the database within the Database connection string. By default, many of the platform providers such as Azure, AWS, and others do not provide the database name in the connection string. This causes a problem because the default name that MongoDB picks if it isn't provided is test which is different from the default database name of the Form.io platform, which is formio. Because of this, we recommend changing all database connections string to change the following

Incorrect:

mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/?ssl=true

Correct:

mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true

Form.io Enterprise API Server Environment

Portal Enabled Environment

It is recommended to enable the Portal during the initial environment creation, as it serves as the connecting mechanism to other environments. Given that the environment is usually restricted due to its connection with the production application, and additional may experience intermittent availability based on the development team's activities, it is advisable for this to be positioned between the and .

By enabling this non-production environment (referred to as the Test stage) amidst your other environments, your Form Builders will be able to work on their Forms within a stable Portal application environment. This setup eliminates the risk of altering the environment while alleviating the instability that may arise from working in other .

Run the following command to spin up your Portal Enabled API server environment.

docker run -d \
  -e "LICENSE_KEY=YOURLICENSE" \
  -e "MONGO=mongodb://mongo:27017/formio" \
  -e "PORT=3000" \
  -e "PORTAL_ENABLED=true" \
  -e "ADMIN_EMAIL=admin@example.com" \
  -e "ADMIN_PASS=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "PDF_SERVER=http://pdf-server:4005" \
  --restart unless-stopped \
  --network formio \
  --link pdf-server:pdf-server \
  --link formio-mongo:mongo \
  --name formio-server \
  -p 3000:3000 \
  formio/formio-enterprise

Once this is done, the server will go through the initialization process and will install the Portal Base project as well as create the initial admin account for the deployment.

Stand-Alone API Environment

Stages provide a way to isolate your Project forms and resources to enable Form Management between different environments.

Now that our Stages have been set up, we can proceed to create our additional production and non-production environment(s) by executing the following command:

docker run -d \
  -e "LICENSE_KEY=YOURLICENSE" \
  -e "MONGO=mongodb://mongo:27017/formio" \
  -e "PORT=3000" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "PDF_SERVER=http://pdf-server:4005" \
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  --link pdf-server:pdf-server \
  --link formio-mongo:mongo \
  -p 3000:3000 \
  formio/formio-enterprise

With these steps completed, you will have independent environments with their respective databases, all conveniently accessible within a unified Portal Application UI.

Allows all communications to be sent through an http proxy. See

Allows all communications to be sent through an http proxy. See

Allows all communications to be sent through an http proxy. See

Google maintains . By following the guidelines and successfully submitting your domain, you can ensure that browsers will connect to your domain only via secure connections. While the service is hosted by Google, all browsers are using this preload list. However, it is not part of the HSTS specification and should not be treated as official.

For more documentation on this feature, please go to

You can also provide Environment Variables through the use of . To utilize Docker Secrets, all of the configuration variables are the same as environment variables. Simply use the same name in docker secrets and the server will use the value. In order to use them, set DOCKER_SECRETS=1 in your environment variables. You can also set DOCKER_SECRETS_PATH to use a path other than /run/secrets.

Prior to deploying your environment, it is important to review the necessary for your deployment. Ensure that variables such as the Database secret are properly configured, and consider enabling the Portal functionality as described below. Taking these steps will help ensure a successful and secure deployment of your environment.

The project is a special project that is used to control the portal application. Any users that can log into the portal are added to the User resource within this project, and anyone with an Authenticated role within this project will have the ability to log in and create new projects.

After the portal has been enabled, you can now login to the portal, by navigating to the root URL of the deployed API. The Admin email and password within the will authenticate you into the Portal.

Prior to creating additional environments, it is crucial to establish within the of the Portal Enabled environment as a means to connect and provide a user interface between the additional environments we will be creating. These stages will be referred to as Developer, Test, and Live, aligning with the provided documentation. It is unnecessary to assign a specific name to the Live stage since it serves as the default production stage once a Project has been created.

for more information

Keep in mind, the created within the step simply serves as an API pathway and User Interface to create, modify, and save JSON for your other environments.

Next, we need to establish to our stages. Within each independent stage, navigate to the Stages settings and access the Connected Environment tab. Enter the environment URL and Portal Secret that was established during the environment creation process.

formio/formio-enterprise
https://github.com/formio/deploy/blob/main/deployments/compose/api-server.zip
https://help.form.io/userguide/actions#template-service
Docker Secrets
environmental variables
Portal Base
environment variables
Stages
Project
Click Here
Portal Application
Portal Enabled Test environment
Remote Connections
https://github.com/request/request#controlling-proxy-behaviour-using-environment-variables
https://github.com/request/request#controlling-proxy-behaviour-using-environment-variables
https://github.com/request/request#controlling-proxy-behaviour-using-environment-variables
an HSTS preload service