forio Toggle navigation

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.

Use Case

There are two main use cases for hosting your project's user interface on your own server:

  • You want to use the Epicenter engine, and communicate with your model via the Epicenter APIs, but want your users to access the simulation on your own website or domain.

  • You want to develop your simulation locally, using your favorite desktop editors and development tools, and don't want to repeatedly upload your project files to Epicenter every time you test the project's user interface.

In both cases, you are still using the Epicenter APIs and any computations in your model are still being executed on the Epicenter backend servers. The frontend code is located on the server of your choice.

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:
  • A location outside of Forio Epicenter where you want to run your project's user interface. This can be your own website, or a local file on your computer. You do NOT need to have a web server (such as Apache) running.

Solution Outline

  1. 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.
  2. Update the parameters for this primary call to include account, project, and server.
  3. Fix any links to external files.

Solution Implementation

  1. 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 (which you'll modify in the next step). These parameters are set in the window.FLOW_CONFIG object in the index.html file generated by the Interface Builder.

  2. Update the parameters for this primary call -- using Flow.js or Interface Builder.

    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 or the Interface Builder, 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' }
                }
            }
        });
      

      Or 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:

        window.FLOW_CONFIG = {
            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' }
                }
            }
        });
      
  3. Update the parameters for this primary call -- using Epicenter.js.

    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'
            }
        });
      
  4. 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: