On-Premise Environments

On-Premise Environments allow running our full API server in your own environment. This will allow having all the form definitions, form data and your project users completely within your own data center or private cloud. On premise deployments are for companies and organizations that do not want or cannot store their data in the cloud.

Environments can be used with projects that are on the Team Pro or Enterprise plan.

Connecting To Portal

Prepare your project

After you have your remote deployment API set up for your backend, you must connect that backend to the Form.io portal. Ensure that you are logged in to Form.io and have a project created that is on Team Pro or Enterprise plan. You cannot connect a project that is not on Team Pro or Enterprise. If you don’t already have one, create a project and upgrade its plan.

Connect to Environment

For each stage of your project that you want to move to a remote environment, go to the Stage Settings on the left and select On-Premise Environments

Enter the Environment URL you set up in the DNS step above. Enter the Portal Secret you added as an Environment Variable to your Environment. Select the Project Path Type you configured in the DNS step above. If in doubt, use Subdirectories.

Finally, press Continue to query the server to make sure it is accessible, compatible and ready. If you get an error message, address the issue in the error message. If successful, you will be presented with a list of Stages on that environment.

Move a stage to an environment

If you have an existing project on your Environment, select it from the list. This will connect your form.io project stage with the existing project. If the project configuration currently exists on form.io or you don’t want to use an existing select New Stage. This will copy all of your settings and forms down to your environment.

Your project stage is now connected to your environment. Any changes are done directly on your On-Premise Environment. It can also be used for staging and deployment and shared with other teams on form.io.

Connect each of your project’s stages to whatever On-Premise environements you want.

Platforms

On-Premise Environments is supported with two different technologies, Docker and Node.js. We recommend using Docker over Node.js as it provides a pre-built and fully tested runtime. When using Node.js it is up to your organization to ensure all the dependencies are installed and up to date.

Whether using Docker or Node, ensure that the installed version is 5.0.0 or later.

Using Docker

Docker instances are run inside a Docker Engine. There are many options for where and how to run a docker instance. Depending on which Docker Engine you are using, the formio server configuration will be different.

Using Cloud Hosted Docker

If you are using a cloud hosted Docker Engine, please follow the appropriate steps to set up the formio server Docker container.

We also have walkthroughs for some hosts.

Installing Docker on localhost for testing

Download and install Docker from https://docs.docker.com/engine/installation/#supported-platforms

Accessing the docker image

Once on a team pro or enterprise plan, you will have access to the docker repository. Our docker images are located on docker hub.

https://hub.docker.com/r/formio/formio-server/

Since the image is a private docker respository, you will need to log in with your docker account and test pulling the image. If you are unable to pull the image, please contact support with your username and account information.

docker login
docker pull formio/formio-server

Create a docker network to contain all the docker instances.

A typical Form.io installation includes a Redis, MongoDB, and a Node.js API Server. If your environment is fully dockerized, you can spin up the stack using the following example commands.

This will create an isolated network for just the formio services that are required to run the server. In addition, it will provide for an easy way to link the services together.

docker network create formio

Create the Mongo instance.

Run mongodb with a volume mount for data. This will store the data in the host machine at /opt/mongodb. If the mongodb instance is restarte or replaced, the data still exists and can be restarted with a different mongodb instance.

On Mac OS running native docker engine, be sure to add ~/opt/mongodb to File Sharing list in Docker->Preferences->File Sharing. You may use a different path if desired.

mkdir ~/opt/mongodb
# Double check permissions on /opt/mongodb
docker run -itd  \
  --name formio-mongo \
  --network formio \
  --volume ~/opt/mongodb:/data/db \
  --restart unless-stopped \
  mongo

Create the Redis instance.

docker run -itd \
  --name formio-redis \
  --network formio \
  --restart unless-stopped \
  redis;

Start the formio-server instance.

Before running this command, you must replace all the CHANGEME secrets with your own custom random strings. This will ensure that the server remains secure.

Set protocol, port and domain to the address where they will be accessible on the external network. For development it is recommended to use port 3000 and for production, use port 80.

PORTAL_SECRET is the secret that will allow the form.io portal to communicate with this server. Please make a note of it as you will need it when connecting your project.

For Stand-alone API Server w/ No PDF Server
docker run -itd \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "PROTOCOL=http" \
  --restart unless-stopped \
  --name formio-server \
  --network formio \
  --link formio-mongo:mongo \
  --link formio-redis:redis \
  --restart unless-stopped \
  -p 3000:80 \
  formio/formio-server;
For Stand-alone API Server with PDF Server
docker run -itd \
  -e "FORMIO_FILES_SERVER=http://formio-files:4005" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "PROTOCOL=http" \
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  --link formio-files-core:formio-files \
  --link formio-mongo:mongo \
  --link formio-redis:redis \
  -p 3000:80 \
  formio/formio-server

NOTE If you are running this container in a production environment and have SSL enabled, then you will need to remove the Environment Variable PROTOCOL

Testing the installation

You should now have an instance of the formio-server running in your environment. To test it, go to http://localhost:3000. You should see a response with an empty array since there will be no projects on your environment yet.

Also test out http://localhost:3000/status which will give you the build number and database schema version of your environment.

Upgrading your deployment

Once you have your Docker container running, you will certainly get to a point where you will need to upgrade your Docker container server. To do this, you simply pull down the latest container, and launch the new instance. Before you update, it is important to stage your commands within a text editor so that you simply need to copy and paste your command in your shell to perform the udpate. To determine the environment variables you will need to call, it is important to ensure that the same environment variables are used from one version to another. You can determine what environment variables to use by typing the following command in your terminal.

docker inspect formio-server

This will print out the information from the formio-server container, including the environment variables. You will then copy those environment variables and merge them with the following command within a Text editor of your chosing.

docker pull formio/formio-server && \
docker rm formio-server-old || true && \
docker stop formio-server && \
docker rename formio-server formio-server-old && \
docker run -itd \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "PROTOCOL=http" \
  --restart unless-stopped \
  --name formio-server \
  --network formio \
  --link formio-mongo:mongo \
  --link formio-redis:redis \
  --restart unless-stopped \
  -p 3000:80 \
  formio/formio-server;

This command pulls down the latest version of the container, stops the current container, renames it to formio-server-old so that you have a path to go back if the update causes any problems, and then launches the new server in its place.

Production Environments

It is very common to setup the Form.io API Server within a scalable environment for production use. Here is some help regarding the best practices on getting an API Server deployed for a Production enviornment.

API Server + Redis

Assuming that you have an external MongoDB setup, the only thing that you will need to configure in addition to a MongoDB server is a Redis instance. You need to use Redis of you plan on using the PDF Server or wish to keep the traffic monitoring within your projects, which keeps track of the traffic for each of your projects. Because this information is non-critical, you can either setup Redis externally, or in some cases this can be managed on the actual API Server. Typically, for a production environment, you would want to have Redis running external, but it is also not considered bad practice to have Redis on the actual server since it is only used to store the temporary download tokens and the worst thing that will happen is that a token would expire if the servers reset. To accomplish this, you will execute the following commands within your terminal.

First create a newtwork that will connect Form.io Server to the local Redis Instance

docker network create formio

Now spin up a local instance of Redis on this server.

docker run -itd \
  --name formio-redis \
  --network formio \
  --restart unless-stopped \
  redis;

Next, spin up your Form.io API server connecting it to the local Redis instance.

docker run -itd \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "PROTOCOL=http" \
  -e "MONGO=mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true" \
  -e "FORMIO_FILES_SERVER=https://pdfserver.yourdomain.com" \
  --network formio \
  --link formio-redis:redis \
  --restart unless-stopped \
  --name formio-server \
  -p 80:80 \
  formio/formio-server;

Note: You will notice that this command also includes a connection to a deployed PDF server using the FORMIO_FILES_SERVER command. If you are not running your own local PDF server, then this command can be ignored.

Note that you would also provide your own URL to the MONGO database and also provide your own domain where you are hosting the PDF server for the FORMIO_FILES_SERVER variable.

API Server Standalone

For some cases, you may wish to keep your Redis database external to your Form.io API server. This would allow for your API servers to become more ephemeral where they can autoscale. If this is the case, then you would provide the following configurations when spinning up your servers. For example, this would be what our Docker command would look like connecting to an ElasticCache instance in AWS.

docker run -itd \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "PROTOCOL=http" \
  -e "MONGO=mongodb://:@aws-us-east-1-portal.234.dblayer.com:23423/formio?ssl=true" \
  -e "REDIS_ADDR=production-001.2iu8pr.0001.usw2.cache.amazonaws.com" \
  -e "REDIS_PORT=6379" \
  -e "FORMIO_FILES_SERVER=https://pdfserver.yourdomain.com" \
  --restart unless-stopped \
  --name formio-server \
  -p 80:80 \
  formio/formio-server;

Some Redis server implementations do require that the connection is over SSL as well as require a password. Azure Redis is a good example of this. For this, you need both REDIS_PASS and REDIS_USE_SSL variables as well. For example, the following is an example of an Azure deployment.

Azure Deployemnt
   docker run -itd \
     -e "PORTAL_SECRET=CHANGEME" \
     -e "JWT_SECRET=CHANGEME" \
     -e "DB_SECRET=CHANGEME" \
     -e "MONGO=mongodb://formio:[PASSWORD]@formio.documents.azure.com:10255/formio?ssl=true&replicaSet=globaldb" \
     -e "REDIS_ADDR=formio.redis.cache.windows.net" \
     -e "REDIS_PORT=6380" \
     -e "REDIS_PASS=[PASSWORD]" \
     -e "REDIS_USE_SSL=true" \
     -e "PROTOCOL=http" \
     --restart unless-stopped \
     --network formio \
     --name formio-server \
     -p 3000:80 \
     formio/formio-server

See Azure Deployments for more information.

PDF Server Deployment

For help on PDF server deployments, please see our help documentation by clicking on the following link.

Local or On-Premise Deployment including API, PDF, Minio, Mongo, and Redis on a Single Server

The following commands can be used to spin up a single server environment that will host all of the necessary dependencies to run the Form.io API server + PDF server all on one server. The following command can be performed on a fresh Unix based system with Docker already installed.

docker network create formio && \
docker run -itd  \
  --name formio-mongo \
  --network formio \
  --volume ~/opt/mongodb:/data/db \
  --restart unless-stopped \
  mongo && \
docker run -itd \
  --name formio-redis \
  --network formio \
  --restart unless-stopped \
  redis && \
docker run -itd \
  -e "FORMIO_FILES_SERVER=http://formio-files:4005" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  -e "PROTOCOL=http" \
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  --link formio-files-core:formio-files \
  --link formio-mongo:mongo \
  --link formio-redis:redis \
  -p 3000:80 \
  formio/formio-server && \
docker run -itd \
  -e "MINIO_ACCESS_KEY=CHANGEME" \
  -e "MINIO_SECRET_KEY=CHANGEME" \
  --network formio \
  --name formio-minio \
  --restart unless-stopped \
  -p 9000:9000 \
  -v ~/minio/data:/data \
  -v ~/minio/config:/root/.minio \
  minio/minio server /data && \
docker run -itd \
  -e "FORMIO_SERVER=http://formio" \
  -e "FORMIO_PROJECT=59b7b78367d7fa2312a57979" \
  -e "FORMIO_PROJECT_TOKEN=wi83DYHAieyt1MYRsTYA289MR9UIjM" \
  -e "FORMIO_PDF_PROJECT=http://formio/yourproject" \
  -e "FORMIO_PDF_APIKEY=is8w9ZRiW8I2TEioY39SJVWeIsO925" \
  -e "FORMIO_S3_SERVER=minio" \
  -e "FORMIO_S3_PORT=9000" \
  -e "FORMIO_S3_BUCKET=formio" \
  -e "FORMIO_S3_KEY=CHANGEME" \
  -e "FORMIO_S3_SECRET=CHANGEME" \
  --network formio \
  --link formio-server:formio \
  --link formio-minio:minio \
  --restart unless-stopped \
  --name formio-files-core \
  -p 4005:4005 \
  formio/formio-files-core;

You will need to change the FORMIO_PROJECT, FORMIO_PROJECT_TOKEN, FORMIO_PDF_APIKEY, and the project name only (“/yourproject”) within FORMIO_PDF_PROJECT. You will also want to change all CHANGEME to a secret password that only you know.

Using Node.js

Native Node.js support is coming soon.

Configuration Options

The formio server is configured with environment variables.

When using Docker, you can set these by using the -e flag. Many Docker hosting platforms have easier ways of setting environment variables for your docker containers.

When using Node.js these variables can either be set in the OS or passed as a prefix to the command. For example: MYVAR=value node index. In addition they can be set in a .env file in the root of the repository.

While we provide many variables to use during a deployment, the recommended configuration should provide the following settings.

Setting 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_SECRET The secret used to connect the portal to your environment [PORTAL SECRET]
DB_SECRET The database encryption secret [DB SECRET]
JWT_SECRET The secret password for JWT token encryption. [TOKEN SECRET]

NOTE: If you are hosting your Form.io API platform without SSL (for testing ONLY), then you will also need to provide the environment variable PROTOCOL set to the value of http.

All Configuration Variables

Below are all the variables that you can set within your On-Premise Environment.

Setting 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
MONGO_HIGH_AVAILABILITY If your database is high availability (like from Mongo Cloud or Compose), then this needs to be set. 1
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_SECRET The secret used to connect the portal to your environment [PORTAL SECRET]
PROTOCOL The HTTP protocol to serve requests. Should be “http” or “https” http
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]
JWT_SECRET The secret password for JWT token encryption. [TOKEN SECRET]
JWT_EXPIRE_TIME The expiration for the JWT Tokens 240
REDIS_ADDR The address of the redis server. This is used for analytics and caching for the Environment. localhost
REDIS_PORT The port of the redis server 6379
REDIS_PASS (Optional) If you redis server has a password, set it with this.  
REDIS_USE_SSL (Optional) If your redis server uses SSL transport protocols, then this can be used to enable that. This is required for Azure Redis deployments  
EMAIL_OVERRIDE Provides a way to point all Email traffic to a server. {“transport”:”smtp”,”settings”:{“port”:2525,”host”:”smtp.mailtrap.io”,”auth”:{“user”:”23esdffd53ac”,”pass”:”324csdfsdf989a”}}}

Using environment variables with Docker

You can set any of these environment variables when you run your Docker deployment by providing the -e parameter. For example, you can run the deployment with some environments set like so.

docker run -d \
    -e "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"\
    -e "MONGO_HIGH_AVAILABILITY=1"
    -e "PORTAL_SECRET=CHANGEME"
    -e "DB_SECRET=CHANGEME"
    -e "JWT_SECRET=CHANGEME"\
    formio/formio-server

Using environment variables with Node.js

You can set these when running the commmand like

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 node index"

You can also set them in a .env file in the root of your repository.

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 node index
MONGO_HIGH_AVAILABILITY=1
PORTAL_SECRET=CHANGEME
DB_SECRET=CHANGEME
JWT_SECRET=CHANGEME

SSL Setup (https)

If you wish to enable SSL (https) configuration for your Environment, then we recommend using NGINX as a reverse proxy to point to the Form.io environment. Follow these steps to get this working.

To setup this configuration, please go through the following steps.

  • Install NGINX using the following command.

    sudo apt-get update
    sudo apt-get install nginx
    

    Or walk through the following tutorial: Installing NGINX

  • We can check to ensure that we have NGINX running with the following command.

    systemctl status nginx
    
  • We now need to edit the nginx.conf file to redirect HTTP traffic to the internal servers.

    sudo vi /etc/nginx/sites-available/formio
    
  • Put the following contents in that file.

     server {
       listen 443 ssl;
       server_name  ~^(www\.)?(.+)$;
       client_max_body_size 20M;
       ssl_certificate      /usr/local/etc/nginx/nginx.crt;
       ssl_certificate_key  /usr/local/etc/nginx/nginx.key;
         
       location / {
         proxy_set_header    Host $host;
         proxy_set_header    X-Real-IP $remote_addr;
         proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header    X-Forwarded-Proto $scheme;
         proxy_pass          http://localhost:3000;
         proxy_read_timeout  90;
         proxy_redirect      http://localhost:3000 https://$host;
       }
     }
    

    In this case, your Environment would be listening to port 3000, and NGINX would serve as the reverse proxy to point to that container.

    If you also have a Minio + PDF Server running on this server, then you will also want to provide them within subdirectories like the following.

     server {
       listen 443 ssl;
       server_name  ~^(www\.)?(.+)$;
       client_max_body_size 20M;
       ssl_certificate      /usr/local/etc/nginx/nginx.crt;
       ssl_certificate_key  /usr/local/etc/nginx/nginx.key;
         
       location / {
         proxy_set_header    Host $host;
         proxy_set_header    X-Real-IP $remote_addr;
         proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header    X-Forwarded-Proto $scheme;
         proxy_pass          http://localhost:3000;
         proxy_read_timeout  90;
         proxy_redirect      http://localhost:3000 https://$host;
       }
        
       location /files/ {
         rewrite ^/files/(.*)$ /$1 break;
         proxy_set_header    Host $host;
         proxy_set_header    X-Real-IP $remote_addr;
         proxy_set_header    X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header    X-Forwarded-Proto $scheme;
         proxy_pass          http://localhost:4005;
         proxy_read_timeout  90;
         proxy_redirect      http://localhost:4005 https://$host;
       }
     }
        
     server {
        listen 443 ssl;
        server_name  ~^minio.(.+)$;
        client_max_body_size 20M;
        ssl_certificate      /usr/local/etc/nginx/nginx.crt;
        ssl_certificate_key  /usr/local/etc/nginx/nginx.key;
         
        location / {
          proxy_buffering off;
          proxy_set_header Host $http_host;
          proxy_pass http://localhost:9000;
        }
     }
    

    Note, for this configuration to work with Minio, you will need to create a subdomain @ http://minio.yourserver.com that points to this server. Minio does not support being hosted outsiide of the root domain.

  • Now save that file, and then switch this out for the default server

     sudo rm /etc/nginx/sites-enabled/default
     sudo ln -s /etc/nginx/sites-available/formio /etc/nginx/sites-enabled/default
     sudo systemctl restart nginx
    

Once you start up your NGINX instance, you will now have an SSL connection into your Form.io Environment!

DNS Setup

In order to run a docker version of the form.io server, a domain name needs to be set up for it. There are now two options for configuring DNS for your docker server. You can run it using subdomains for multiple projects or run on a single domain and have projects as subdirectories of that domain.

Subdirectories

When using Subdirectories to refer to projects, simply set up a single domain and point it to the server. All projects will become subdirectories of that domain instead of subdomains. Be sure to select “Subdirectory” from the Project Path Type in the environment switcher.

For example: https://myformio.mydomain.com

If using subdirectories, skip the Subdomains section.

Subdomains

When using subdomains, the server DNS must have the following three domains set up and an additional one per project OR have a wildcard subdomain entry in the DNS server.

Every deployment needs the following 3 subdomains to function.

HostName Description
api.yourdomain.com This subdomain points to the core API of the Form.io platform.
formio.yourdomain.com This points to the Main Form.io project which is required to login and manage your deployment.
[YOURPROJECT].yourdomain.com This points to the project within the deployment, which is your applications Form.io project.

For the following scenarios, assume the following project was created on the docker instance.

{
    "title": "My Project",
    "name": "myproject",
    "_id": "55882653b213f00a2641585d"
}
Localhost

For local testing, localhost would seem like a logical solution, however, since formio server relies on subdomains to manage projects and localhost does NOT support subdomains, it becomes a lot of work to constantly add additional lines to the /etc/hosts file each time a project is created.

Instead, we recommend using a domain name with wildcard subdomain support already set up that points to 127.0.0.1. This will allow using a real domain name but will point at your localhost.

http://lvh.me is the domain we recommend. If you run the server and use this domain to point to it, the server with subdomains will work correctly.

To access a project, use the project name and lvh.me

GET http://lvh.me:3000/project/55882653b213f00a2641585d
GET http://myproject.lvh.me:3000/

If you do not want to use lvh.me or a similar domain, you may use the /etc/hosts file (or the Microsoft Windows equivalent).

To use localhost, add the following items and any other project subdomains created on the server.

127.0.0.1   localhost
127.0.0.1   formio.localhost
127.0.0.1   api.localhost
127.0.0.1   myproject.localhost

Then, to access the project, use one of the following methods

GET http://localhost:3000/project/55882653b213f00a2641585d
GET http://myproject.localhost:3000

Each time a new project is added to the server for testing, be sure to add another entry to /etc/hosts.

Public Domains

For publically available servers such as testing and production, set up a wildcard subdomain to point to the server. This will allow subdomains to route correctly to your server. For example, you should have something like this in your DNS settings:

*.example.com.   3600 IN  MX 10 host1.example.com.

See https://en.wikipedia.org/wiki/Wildcard_DNS_record for more information on setting up a wildcard DNS entry.

Then, to access the project, use one of the following methods

GET https://example.com/project/55882653b213f00a2641585d
GET https://myproject.example.com

For all domains other than localhost it is best practice to set up SSL Certificates and run the server over https. This both keeps communication secure and also some browsers are starting to require https for certain cross browser requests.