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

Redis can be easily created within your instance by running the following command.

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

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 \
  --link formio-redis:redis \
  --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 \
  --link formio-redis:redis \
  -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 \
  --link formio-redis:redis \
  --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

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 "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" \
  --network formio \
  --link formio-redis:redis \
  --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.

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 "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 "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-enterprise;

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 Deployment

Within Azure, you will most likely be connecting this deployment to a Cosmos DB as well as a Azure Redis server. For this kind of deployment, your command 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://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" \
 --restart unless-stopped \
 --network formio \
 --name formio-server \
 -p 3000:80 \
 formio/formio-enterprise

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 "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 \
  --link formio-redis:redis \
  -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.

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