How To: Host an Epicenter Project on Your Own Server | Documentation

How To: Host the User Interface of an Epicenter Project on Your Own Server

All Epicenter projects are available at https://forio.com/app/{your team id or user id}/{your project id}/. (See more details.)

However, you can also host the user interface of Epicenter projects on your own server. This example describes how.

What You Need

An Epicenter project.
An interface for your project. For purposes of this example, we assume you've created your interface using either:
- Flow.js,
- Epicenter.js,
- Or the Interface Builder (which generates code that uses Flow.js).
A location outside of Forio Epicenter where you want to run your project's user interface. This should be a webserver that can host HTML, images, and/or CSS and JS files.

Note: In the past it was feasible to host Forio simulations as local files (without a web server), however modern browser security limitations prevent API calls being made from local files to web servers by default.

Solution Outline

Find the primary run creation call, or parameters for it, in your user interface code.
- If you are using Flow.js, this is a Flow.initialize() call.
- If you are using Epicenter.js, this is probably the creation of a Run Manager, Run Service, or Data Service. For example: var rs = new F.service.Run() or var ds = new F.service.Data().
- If you are using the Interface Builder, these parameters are in your index.html file.
Update the parameters for this primary call to include account, project, and server.
Fix any links to external files.

Solution Implementation

Find the primary run creation call in your user interface code.

If you are using Flow.js, this is a Flow.initialize() call. If you are using Epicenter.js, this is likely a new F.service.Run() or new F.service.Data() call.

If you created the user interface for your project with the Interface Builder, you don't need to find the call, just the parameters. These parameters are set in the window.FLOW_CONFIG object in the index.html file generated by the Interface Builder.

Update the parameters for this primary call to include account, project, and server.

Below are details on how to do this for projects using Flow.js, the Interface Builder, and with Epicenter.js.

Flow.js: Provide account, project and server parameters when initializing the page.

When you access your project from Epicenter, hosted at https://forio.com/app/{your team id or user id}/{your project id}/, the correct values for account (User ID or Team ID), project (Project ID), and server are automatically detected and set. When designing your project to be accessed from a different server, you need to set the values manually.

If you are using Flow.js these values are part of a channel.run parameter, and you'll need to set them yourself. Add three new fields inside the channel.run parameter:

account: The Team ID (for team projects) or User ID (for personal projects).
project: The Project ID.

server: An object with one field, host. The value of host is the string api.forio.com.

For example,

  Flow.initialize({
      channel: {
          run: {

              // the model field should already be present
              model: 'myModel.vmf',

              // add the account, project, and server fields
              account: 'acme-simulations',
              project: 'supply-chain-game',
              server: { host: 'api.forio.com' }
          }
      }
  });

Interface Builder: Provide account, project and server parameters when initializing the page.

If you are using the Interface Builder, you can make the update in the variable that's automatically created in index.html to hold your Flow.js configuration information. Note, the specifics will vary depending on whether the simulation is a turn-by-turn simulation, a run comparison simulation, or a multiplayer simulation.

For a turn-by-turn interface builder simulation you will want to do something similar to this:

  var accountName = "acme-simulations";
  var projectName = "supply-chain-simulation";
  window.FLOW_CONFIG = {
      channel: {
          defaults: {
              account: accountName,
              project: projectName,
              server: {
                  host: 'api.forio.com'
              },
          },
          runManager: {
              run: {
                  account: accountName,
                  project: projectName,
                  server: {
                      host: 'api.forio.com'
                  }
              },
          }
      }
  };

For a run comparison interface builder simulation you will want to do something similar to this:

  var accountName = "acme-simulations";
  var projectName = "supply-chain-simulation";
  window.FLOW_CONFIG = {
      channel: {
          defaults: {
              account: accountName,
              project: projectName,
              server: {
                  host: 'api.forio.com'
              },
          },
          runManager: {
              run: {
                  account: accountName,
                  project: projectName,
                  server: {
                      host: 'api.forio.com'
                  }
              },
          },
          scenarioManager: {
              run: {
                  account: accountName,
                  project: projectName,
                  server: {
                      host: 'api.forio.com'
                  }
              },
          }
      }
  };

Multiplayer simulations built in the interface builder do not currently support hosting on non forio.com domains.

Epicenter.js: Update the parameters for the primary call.

If you are using Epicenter.js, these values are part of the options object passed to a Run Service or Data Service. Add these new fields inside the options parameter:

account: The Team ID (for team projects) or User ID (for personal projects).
project: The Project ID.
server: An object with one field, host. The value of host is the string api.forio.com.

For example,

  var rs = new F.service.Run({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      server:  { host: 'api.forio.com' },
      model: 'myModel.vmf'
  });

  var ds = new F.service.Data({
      account: 'acme-simulations',
      project: 'supply-chain-game',
      server:  { host: 'api.forio.com' },
      root: 'survey-responses'
  });

If you are using the Run Manager, remember that the first parameter is the instantiated Run Service. So the account, project, and server fields go inside the run object in the options parameter:

  var rm = new F.manager.RunManager({
      run: {
          account: 'acme-simulations',
          project: 'supply-chain-game',
          server:  { host: 'api.forio.com' },
          model: 'myModel.vmf'
      }
  });

Fix any links to external files.

You may need to fix some of the links to external script files. In particular:

Any script files whose src begins with '//' should be updated to begin with 'https://'.

For example,

      <script src="//forio.com/tools/js-libs/...">
      <script src="//ajax.googleapis.com/ajax/libs/...">

should be changed to

      <script src="https://forio.com/tools/js-libs/...">
      <script src="https://ajax.googleapis.com/ajax/libs/...">

Any links that reference local files either need to be updated, or those referenced files need to be copied to the location where you are hosting your user interface.

For example, these links generated by the Interface Builder:

  <!-- these are immediately above the window.FLOW_CONFIG declaration in index.html-->
  <link rel="import" href="/epicenter/builder/templates/web-components/contour.htm">
  <link rel="stylesheet" href="/epicenter/builder/templates/styles/modern-theme.min.css">
  <link href="/epicenter/builder/templates/common.min.css" rel="stylesheet"><script>

  <!-- these are near the bottom of index.html -->
  <script type="text/javascript" 
      src="/epicenter/builder/templates/vendor.min.js"></script>
  <script type="text/javascript" 
      src="/epicenter/builder/templates/common.min.js"></script>

all need to be updated: they all need to be prefaced with https://forio.com.

Important Notes

Your model file (myModel.vmf in the example code above) still must be uploaded to your Epicenter project and placed in the Model folder there.
Wherever you run your project, you are still using the Epicenter APIs and any computations in your model are still being executed on the Epicenter backend servers. Only the user interface is hosted on your server. In particular, this means that the Model Session Timeout and Dedicated Compute Units as set in your project settings still apply.

See it in Action

Watch a short video describing this solution on the Forio YouTube channel:

Note -- this video refers to out of date technique where the file can be run locally by opening the HTML file in your browser. This no longer works due to browser updates which add default security settings preventing files from being loaded. As noted above, the files need to be hosted on a web server.