Enterprise Server
Let's deploy the main on-premise product of Form.io. The Enterprise Server.
We will start our deployment with the Form.io Enterprise Server, which can be found on Docker Hub at the following URL.
This 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.
Here are the variables that are available for the formio/formio-enterprise deployments.
Environment Variable | Description | Example |
LICENSE_KEY (7x Server only) | A valid license obtained from form.io. | abcdefghi1234567890 |
LICENSE (6x Server Only) | The license environment variable used for 6.x server versions only. | A long JWT token |
Environment Variable | Description | Example |
MONGO | The MongoDB connection string to connect to your remote database. | mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true |
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_PASS | If PORTAL_ENABLED is set to "true", this is used to determine the password of the default root user login | CHANGEME |
DB_SECRET | The database encryption secret | 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 | If a PDF Server is deployed, this is the "internal" dns url for the PDF server | http://pdf-server:4005 |
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 | Prevents accounts created using the User resource from creating Projects | 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 | Allows all communications to be sent through an http proxy. See https://github.com/request/request#controlling-proxy-behaviour-using-environment-variables | |
HTTPS_PROXY | Allows all communications to be sent through an http proxy. See https://github.com/request/request#controlling-proxy-behaviour-using-environment-variables | |
NO_PROXY | Allows all communications to be sent through an http proxy. See https://github.com/request/request#controlling-proxy-behaviour-using-environment-variables | |
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. | |
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=truemongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=trueThe deployed Form.io platform is also capable of offloading all email template processing to a separate micro-service, which is called a Template Service. The code for this service is implemented at the following Github Url.
For more documentation over this feature, please go to https://help.form.io/userguide/actions#template-service
You can also provide Environment Variables through the use of Docker Secrets. 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.
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:[email protected]:234234,aws-us-east-1-portal.26.dblayer.com:234234/formio?ssl=true
PORTAL_SECRET=CHANGEME
DB_SECRET=CHANGEME
JWT_SECRET=CHANGEME
As mentioned above, a Portal Environment enables both the Developer Portal as well as the backend API's for the Projects, forms, submissions, etc. The Docker command to launch a Portal Environment is as follows.
docker run -d \
-e "LICENSE_KEY=YOURLICENSE" \
-e "MONGO=mongodb://mongo:27017/formio" \
-e "PORT=3000" \
-e "PORTAL_ENABLED=true" \
-e "[email protected]" \
-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
If you are deploying the 6.x version of our deployments, you will need to replace LICENSE_KEY environment variable with LICENSE and use the 6.x license for the value instead.
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 this deployment.
The Portal Base 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 the 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 just navigating to the root url of the deployed API.
To deploy a production ready API Environment, the following command can be used.
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
After you have your remote deployment API set up, you can now connect that backend using the Hosted Form.io portal found at https://portal.form.io. Ensure that you are logged in to Form.io and have a project created that is on the Enterprise plan. If you don’t already have one, create a project and upgrade its plan.
Within your project, or within each stage of your project, you can now connect to your remote environment by going to the Stage Settings on the left and select On-Premise Environments
Connecting portal to a remote environment
Last modified 2mo ago