On-Premise Environments

These instructions are for the 6.x formio-enterprise release and before. If you are using 7.x or later, please go to the new documentation

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 with an additional on premise License.

Platforms

On-Premise Environments are 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.

Docker is available via a public docker respository at https://hub.docker.com/r/formio/formio-enterprise and can be used with a license.

Please contact support for information on how to deploy with an npm package.

On Premise Portal and Primary Environment

You can enable the portal interface (Application UI) of the server for your on premise server. This is available in v6.1.0 and above.

Design

When enabling the portal it is important to think about how you want your environment architecture to work. Typically you will set up one environment as your primary environment and the rest as secondary environments. Please note that environments can have multiple servers which should share the same PRIMARY setting.

            Primary
               |
        |--------------|
    Secondary       Secondary
   

You should only have ONE primary environment installed. Each primary environment will have a different set of users, teams and projects so installing multiple primary environments can result in multiple user accounts and confusion.

Difference between Primary and Secondary Environments

A primary environment has additional features and functionality that a secondary server does not.

  • Portal Base Project - A project is installed on the Primary Environment called “Portal Base”. This project is the project that contains the user accounts, login and register forms for the environment. You can use this to manage users and access to the portal application. This project will contain the users, admins and teams of the portal.
  • Portal Application - The portal application will be served from the root of the server. If you have a DNS entry of forms.myserver.com pointed to the environment, http://forms.myserver.com can be used to access the portal application.

A secondary environment will NOT have the portal app and project available on it.

Setting an environment as Primary or Secondary

When setting up your primary environment, you will need to set an additional environment variable of PRIMARY=true. When a server is started like this it will automatically install the Portal Base project and set up a “super admin” user. The username and password for the “super admin” user will be output during the install process. If you want to specify the admin and password, you can set them as environment variables before the first time the install is run. The variables are ADMIN_EMAIL and ADMIN_PASS

To start a server a Secondary, don’t set the PRIMARY environment variable or set it to false. Be sure to set PORTAL_SECRET on your secondary environment. This will be used to connect the Secondary Environment to your Primary Environment.

Connecting a Secondary Environment to a Primary Environment

To add a project to a secondary environment, first, create it on the Primary Environment using the On Premise Portal. Then, go to Settings -> Stage Settings -> On Premise Environments. Connect it to the Secondary Environment using the url and portal secret for the Secondary Environment. This will copy over all form and resource definitions to the secondary environment.

Migrating existing environments to on premise portal/primary environments

If you have been using our hosted portal to manage your on premise projects, you can follow the same process for setting up an on premise portal. There will be two additional steps you need to do to finish adding on premise portal.

  1. Set up users and teams. Your on premise portal will start out without any users and teams. You will need to set up the users and teams instead of using the hosted users and teams. You can also connect the Portal Base / User Login Form to connect to LDAP or OAuth.
  2. Set an owner on existing projects. Your existing projects will still existing in the database but the super admin user will not have access to them so they won’t show up within the portal. To fix this, get the user id of the super admin and change the “owner” property of each project in the database. The method to do this is different depending on the type of access you have to the database.

Enterprise License

The form.io Server Enterprise Edition requires a license to run. To obtain a license, purchase a team pro or enterprise project and contact our support. They will send you a license that can be used with your server.

Once you have the license, set it in an environment variable called LICENSE for either Node.js or Docker, depending on your run method.

The enterprise server will not start without a license.

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

Our docker images are located on docker hub.

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

To pull it down, run the following docker command.

docker pull formio/formio-enterprise

Create a docker network to contain all the docker instances.

A typical Form.io installation includes a 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 restarted 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

Start the formio-enterprise instance.

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

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 "LICENSE=YOURLICENSE" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  --restart unless-stopped \
  --name formio-server \
  --network formio \
  --link formio-mongo:mongo \
  --restart unless-stopped \
  -p 3000:80 \
  formio/formio-enterprise;
For Stand-alone API server with Deployed Portal interface

This command will install the API server, but also include the Deployed portal interface along with an admin account which will let you log into the portal.

docker run -itd \
  -e "ADMIN_EMAIL=admin@example.com" \
  -e "ADMIN_PASS=CHANGEME" \
  -e "PRIMARY=true" \
  -e "LICENSE=YOURLICENSE" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  --restart unless-stopped \
  --name formio-server \
  --network formio \
  --link formio-mongo:mongo \
  --restart unless-stopped \
  -p 3000:80 \
  formio/formio-enterprise;
For Stand-alone API Server with PDF Server

If you are running a PDF server within the same server as your deployment, you will also want to connect this deployment to the running instance of the PDF server. This can be done using the following command.

docker run -itd \
  -e "LICENSE=YOURLICENSE" \
  -e "FORMIO_FILES_SERVER=http://formio-files:4005" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  --link formio-files-core:formio-files \
  --link formio-mongo:mongo \
  -p 3000:80 \
  formio/formio-enterprise

Testing the installation

You should now have an instance of the formio-enterprise running in your environment. To test it, go to 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-enterprise && \
docker rm formio-server-old || true && \
docker stop formio-server && \
docker rename formio-server formio-server-old && \
docker run -itd \
  -e "LICENSE=YOURLICENSE" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  --restart unless-stopped \
  --name formio-server \
  --network formio \
  --link formio-mongo:mongo \
  --restart unless-stopped \
  -p 3000:80 \
  formio/formio-enterprise;

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.

Upgrading Stand-alone MongoDB

In some cases, you may have a local MongoDB running where you would also wish to upgrade the MongoDB container. You must be careful when doing this since removing a container could remove your database. Because of this, the following commands should be performed when upgrading a local stand-alone MongoDB database container.

# Backup the current database into "/tmp/mongoexport"
docker run -i --rm --network formio --link formio-mongo -v /tmp/mongoexport:/tmp mongo bash -c 'mongodump -v --host formio-mongo:27017 --out=/tmp';

# Stop and remove the running mongo server.
docker stop formio-mongo;
docker rm formio-mongo;

# Move the current mongo directory to a backup folder in case the import fails.
sudo mv ~/opt/mongodb ~/opt/mongodb-backup;

# Pull the latest version of Mongo.
docker pull mongo;

# Start up a new container with the latest version of MongoDB.
docker run -itd  \
  --name formio-mongo \
  --network formio \
  --volume ~/opt/mongodb:/data/db \
  --restart unless-stopped \
  mongo;

# Import the export into the mongodb container.
docker run -i --rm --network formio --link formio-mongo -v /tmp/mongoexport:/tmp mongo bash -c 'mongorestore -v --noIndexRestore --host formio-mongo:27017 /tmp';

Production Environments

For Production deployments, it is recommended to host your Mongo Database within an external service. With this, you will use the MongoDB connection string to connect the API Server to the remotely hosted database. This will look like the following.

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

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.

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 \
  -e "LICENSE=YOURLICENSE" \
  -e "FORMIO_FILES_SERVER=http://formio-files:4005" \
  -e "PORTAL_SECRET=CHANGEME" \
  -e "JWT_SECRET=CHANGEME" \
  -e "DB_SECRET=CHANGEME" \
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  --link formio-files-core:formio-files \
  --link formio-mongo:mongo \
  -p 3000:80 \
  formio/formio-enterprise && \
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.

Docker Secrets

Our Enterprise server also supports the Docker Secrets feature which allows you to store the Environment variables in a secure way. Go to https://docs.docker.com/engine/swarm/secrets for more information.

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.

Docker Compose

Docker Compose provides a way to setup the entire deployment within a single script. Here is an example Docker Compose file. Please follow the following steps to get Form.io working within Docker Compose.

  • Install Docker to your local machine.
  • Copy the following text below into a file called docker-compose.yml
  • Get a temporary LICENSE by contacting support@form.io
  • Once you receive your license, paste this as the value for the LICENSE: environment variable within the docker-compose.yml file.
  • Type docker-compose up within your terminal.
  • This will install all dependencies locally and run the server @ http://localhost:3000 on your machine.
  • Login using the credentials admin@example.com and CHANGEME as the password.
  • You should see a project called “Portal Base”, open this project and then navigate to Settings > Stage Versions > Import Template
  • Download the PDF Project to your local machine, and then import that into the Portal Base project
  • Next navigate to Settings > Stage Settings > API Keys and create an API key for this project.
  • Next navigate to Settings > PDF Management and then click on the Enterprise tab.
  • Copy the value of the FORMIO_PROJECT and then request support@form.io to enable this project for Enterprise plan.
  • Once this is done, you can then copy the following values and paste them into the docker-compose.yml file. Note: Your values will be different
    • FORMIO_PROJECT: 5d03208cf1fefc22cbefaa1d
    • FORMIO_PROJECT_TOKEN: 1ntb8zE4LhoaaekMMKQQ3kMakr1kUN
    • FORMIO_PDF_PROJECT: http://formio/formio
    • FORMIO_PDF_APIKEY: UzEevZFX9dXjIQ982E3aTIi9Ir3rAi
  • Re-install the docker compose by typing the following.

        docker-compose stop
        docker-compose rm
        docker-compose up
    
  • You should now have a completely working local Enterprise environment of Form.io.

docker-compose.yml

version: '3.7'
services:
  mongo:
    image: mongo:4.2
    restart: always
    volumes:
      - mdb-data:/data/db
    networks:
      formio:
        aliases:
          - mongo
    environment:
      MONGO_INITDB_ROOT_USERNAME:
      MONGO_INITDB_ROOT_PASSWORD:
  minio:
    image: minio/minio
    restart: always
    volumes:
      - minio-data:/data
      - minio-config:/root/.minio
    ports:
      - "9000:9000"
    networks:
      formio:
        aliases:
          - minio
    environment:
      MINIO_ACCESS_KEY: CHANGEME
      MINIO_SECRET_KEY: CHANGEME
    command: server /data
  formio:
    image: formio/formio-enterprise
    restart: always
    ports:
      - "3000:80"
    networks:
      formio:
        aliases:
          - formio
    environment:
      PRIMARY: 1
      ADMIN_EMAIL: admin@example.com
      ADMIN_PASS: CHANGEME
      FORMIO_FILES_SERVER: http://formio-files:4005
      LICENSE:
  formio-files:
    image: formio/formio-files-core
    restart: always
    ports:
      - "4005:4005"
    networks:
      formio:
        aliases:
          - formio-files
    environment:
      FORMIO_SERVER: http://formio
      FORMIO_PROJECT:
      FORMIO_PROJECT_TOKEN:
      FORMIO_PDF_PROJECT: http://formio/formio
      FORMIO_PDF_APIKEY:
      FORMIO_S3_SERVER: minio
      FORMIO_S3_PORT: 9000
      FORMIO_S3_BUCKET: formio
      FORMIO_S3_KEY: CHANGEME
      FORMIO_S3_SECRET: CHANGEME
networks:
  formio:
volumes:
  mdb-data:
  minio-data:
  minio-config:

Using Node.js

The Node version of the form.io Server Enterprise Edition is run in a Node.js context. This can be any Node.js 8.x or above.

Accessing the GitHub image

Once on a team pro or enterprise plan, you will need to have access to the private repository. Our private repositories are located on GitHub.

https://github.com/formio/formio-enterprise

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

Follow the directions in the Readme of the formio-enterpise repository to finish the setup.

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.

Required Configuration Variables

You must obtain and add a LICENSE variable or the server will not start.

Setting Description Example
LICENSE A valid license obtained from form.io. abc123

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]

All Configuration Variables

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

Setting 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_HIGH_AVAILABILITY If your database is high availability (like from Mongo Cloud or Compose), then this needs to be set. 1
MONGO_SA A custom SSL certificate authority PEM contents. See https://mongodb.github.io/node-mongodb-native/2.2/tutorials/connect/ssl  
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  
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]
PRIMARY Set whether this environment is a primary environment or not. false
ADMIN_EMAIL The default email of the super admin account. Only on initial startup of Primary. [email]
ADMIN_PASS The default password of the super admin account. Only on initial startup of Primary. [password]
PORTAL_SECRET The secret used to connect the portal to your environment [PORTAL SECRET]
FORMIO_FILES_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 https://pdf.yourserver.com
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
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”}}}
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
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  

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 "LICENSE=YOURLICENSE" \
  -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"\
  --restart unless-stopped \
  --network formio \
  --name formio-server \
  -p 3000:80 \
  formio/formio-enterprise

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

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.