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.


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.


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 \

Create the Redis instance.

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

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.

docker run -itd \
  -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 \

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 "PROTOCOL=http" \
  --restart unless-stopped \
  --name formio-server \
  --network formio \
  --link formio-mongo:mongo \
  --link formio-redis:redis \
  --restart unless-stopped \
  -p 3000:80 \

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.

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

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

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.

Now, you will need to configure your nginx.conf file. You will be setting up NGINX to serve as a reverse proxy to the Environment. The following configuration is an example of what would work.


server {
    listen       443 ssl;
    server_name  *.lvh.me;
    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;

        # Fix the “It appears that your reverse proxy set up is broken" error.
        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.

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.


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.


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"

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 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.   localhost   formio.localhost   api.localhost   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

Ensure that you have a project created and that it 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 an 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.