Deployment

Introduction

Once you are happy with the MIRO application you developed, you can deploy it. This chapter guides you through this process.

Deploying a MIRO application is the process of exporting and installing your app so that it can be easily shared and used in the daily business of your end users. Before you can deploy an app, it needs to be fully set up: no further changes to the model or the configuration can be made once it is deployed. In case you did not configure your MIRO app yet, read the chapters about model preparation and configuration.

App deployment - step by step

The deployment of an application consists of two parts: The creation of a self-contained app bundle and its installation.

Create an app bundle

The model assembly file:

Before you export your app bundle, MIRO needs to know about the files that belong to your model. This is primarily the main model file, but also all files necessary to calculate all inputs and outputs, e.g. files that are included in the model. To tell MIRO about these files, create a text file in the root directory of your model called <modelname>_files.txt or use GAMS Studio to create this file for you. For the latter you can select in the menu MIRO under create model assembly those folders and files which are needed. If you select a folder, all files in it will be included. If you want to use only single files of a folder, you have to expand the folder and select the corresponding file(s).

create model assembly file
Attention

In case you have specified custom analysis scripts, make sure to include these here as well!

If you want to create the text file on your own, specify the relative paths to the files that are part of your model separated by a new line. An example for a model named example can be found below:

example_files.txt

example.gms
data
inc/inc1.inc
inc/inc2.inc
                                    

This would result in the files example.gms, inc/inc1.inc, inc/inc2.inc and the entire directory data to be included.

Export app:

Once you specified the files that belong to your model, you are ready to export your MIRO app!

Deploy MIRO model

In GAMS Studio, select Deploy and specify which MIRO modes you want to support in your MIRO app (Base Mode/Hypercube Mode or both). If the Base Mode is selected, you also need to decide how your model shall be executed (execution environment). There are three options:

  1. Multi-user: This option allows your app to be used by multiple users simultaneously. Your model files are extracted at a random location, which is different for each user, and your model is executed from there.
  2. Single-user: Your model is executed inside the model directory. No extraction of your model files is required, but this means that you can NOT have multiple users accessing your MIRO app at the same time.
  3. Local multi-user (uses idir): With this third option, your model is again executed from a random location, but this time no model data is extracted here. Instead, GAMS is executed with an input directory pointing to the path where your model files are located. Choose this option ONLY if you have many large files that belong to your model and extracting them would take a long time. Be aware that due to the fact that idir is used, your model might brake! For example, if you use $call or the execution-time equivalent execute (or related functions), the relative paths used in these calls will no longer exist (since the curdir is now a random location). The solution is to prefix all these relative paths with %gams.idir1%. For example, in order to import an Excel file test.xlsx, GDXXRW needs to be called like this: $call gdxxrw i=%gams.idir1%test.xlsx. Alternatively, you can also use absolute paths (e.g. via $setNames "%gams.input%" fp fn fe (see here).
    Adjusting all affected paths is potentially a lot of work, so we strongly advise against using this option unless you know what you are doing!
Advice

We advise you to test your MIRO app before distributing it. GAMS Studio offers an option test deployment. This simulates how your end users will experience the MIRO app (e.g. for the Base Mode MIRO is launched in the specified execution environment). In particular, you should check whether you forgot to include important files in the model assembly <modelname>_files.txt.

Bundling data with your app

In case you want to distribute scenario data with your MIRO application, you can do so by simply placing GDX files in the data_<modelname> directory. When your MIRO app is started for the first time, these datasets will be stored in the MIRO database. The filename is used as the scenario name. To learn more, read the chapter on importing multiple scenarios on startup. Note that the owner of these scenarios is the user that launches the MIRO app for the first time!

Assign a default logo

When adding the MIRO app to the MIRO library, the user has the option to choose a logo to quickly identify your app. If you want to suggest a logo, simply place am image (format: png/jpg/jpeg; aspect ratio: 8 × 5 fits best) with the name app_logo inside the static_<modelname> folder before deploying. When a user imports your app, this logo will be suggested to them. If no such file is found, a default logo is used.

Custom Logo for MIRO library

Note: The app_logo logo described here is located in the same folder, but is independent of the logo set in the Configuration Mode.

Specify a default title and description for your app

When adding a new MIRO app to the library, a user can specify an app title as well as a short description. If you want to provide defaults for these, you can do so via a JSON file app_info.json inside the static_<modelname> folder. The JSON file has to have the following structure:

{
    "title": "Example app",
    "description": "This is my first MIRO app"
}

If everything is set, click on Deploy. That's it! A new file <modelname>.miroapp is created in your model directory. You can now distribute this MIRO app directly to your end users!

Advanced: Export MIRO app using the command line

Install the MIRO app

To install a new MIRO app, launch GAMS MIRO Desktop. You will see your personal MIRO library with all the MIRO apps you have installed.

MIRO gallery example

To add a new app to the library, either double click the app in your file browser (only on Windows/macOS) or click on "Edit" (Ctrl + E or + E on macOS) and drag&drop the app onto the "+" button. Alternatively, you can click on the "+" button and browse to the location of the new app manually.

Add new app

Once MIRO validated the new app, you can assign a title, a short description as well as a logo.

Edit MIRO app

Once you are happy with the setup, click on Add app. Your app is now installed in your library and you can launch it by clicking the Launch button. In case your app supports both the Base Mode and the Hypercube Mode, the Launch button turns into a dropdown menu that lets you select which mode to launch.

Launch Base or Hypercube Mode
Note

It is not possible to start MIRO applications in development mode (via GAMS Studio or command line) when the MIRO library is open!

Customize your installed MIRO apps

The MIRO Desktop interface offers several ways to control the behavior of your MIRO apps. To access these settings click on FilePreferences (or GAMS MIROPreferences if you are on macOS). Alternatively, press F7 (or + , on macOS). You will notice that there are two categories of settings: General settings and settings related to Paths. In the General category you can specify whether you want to launch your MIRO apps in a new window of the MIRO Launcher or in your default browser. You can set the language, specify the level of detail of information to be logged as well as the number of days you want your log files to be stored for (-1 being no limit)

Furthermore, in the Paths section, you can control the location where your MIRO apps are stored/loaded from and the location where log files are kept. Additionally, in case you want to use a specific GAMS or R version or the MIRO Launcher was unable to locate GAMS (or R) automatically, you can set the path to GAMS (or R) here.

Option Description
General Launch MIRO apps in your browser? If this option is set, MIRO applications are started in the users default web browser. If not set, the internal chromium browser is used instead.
Language Sets the language. The user can choose between English, German and Chinese. Further languages are planned.
Execution of models on GAMS Engine? If enabled, GAMS jobs can be run in the cloud instead of on the local machine. For this purpose the server information must be specified in the MIRO application. This option can also be enabled by setting the environment variable MIRO_REMOTE_EXEC to true.
Logging level Determines the logging scope. TRACE = very high, FATAL = very low
Number of days log files are stored A value of -1 means that the logs are never deleted.
Paths MIRO app path Path to the working directory of GAMS MIRO. There deployed apps are stored, Hypercube Jobs are executed and log files are written. On Windows the default location is C:\Users\<username>\.miro
GAMS path Path to the GAMS installation folder.
Log path Location where the log files should be saved.
R path Path to the R location. A current R version (3.6 or later) is required for using GAMS MIRO. Since R is bundled with MIRO on Windows and MacOS, this option is only available on Linux systems.

Collaboration

Share MIRO apps

This section covers the options you have when you want to share MIRO apps and/or scenarios between multiple users.

First, you need to specify a location in your file system where your MIRO apps are stored. To change the directory where MIRO apps are stored, go to PreferencesPaths and change the "MIRO app path" to a directory where all collaborating users have at least read access. Users that are allowed to add/edit/remove apps need write access as well. Note that this only handles the location of where the MIRO apps are stored and loaded from, not the location of the MIRO database that the apps use. If you want your users to share the same database (in order to collaborate), you can specify its location by clicking on Edit (Ctrl + E or + E on macOS).

Edit database location
Note

Collaborators need both read and write permissions at the database location to load and save scenarios!

Share settings

In addition to sharing MIRO apps, you may want to share settings such as "Paths" to the GAMS/R installation or even "General" settings such as the log file verbosity. To do so, you have to create a file: settings.json at the location of the shared MIRO app path.

Let's look at an example: You created a shared directory <sharedFolder> where you have read and write access and all the other collaborators only have read permissions. You select this directory in your MIRO settings (PreferencesPathsMIRO app path) and install your MIRO applications here. In addition, you want to set some default settings. Therefore, you create a file <sharedFolder>\settings.json:

{
    "gamspath": "C:\\GAMS\\win64\\30.2",
    "launchExternal": false,
    "logLifeTime": -1,
    "important": ["logLifeTime", "gamspath"]
}

Users that set their MIRO app path to <sharedFolder> will now also load these settings in addition to the apps installed here (in this example the GAMS path is set to C:\GAMS\win64\30.2, the MIRO app is not launched in the default browser but inside a native MIRO window and the logs are never removed).

The "important" key is special: settings listed here ("logLifeTime" and "gamspath") will be fixed, meaning the user can not overwrite these. This is useful if you don't want your users to change certain options.

The schema for the settings.json file is as follows:

{
  configpath: {
    type: 'string',
    minLength: 2
  },
  gamspath: {
    type: 'string',
    minLength: 2
  },
  rpath: {
   type: 'string',
   minLength: 2
  },
  logpath: {
    type: 'string',
    minLength: 2
  },
  launchExternal: {
    type: 'boolean'
  },
  logLifeTime: {
    type: 'integer',
    minimum: -1
  },
  language: {
    type: 'string',
    enum: ['en', 'de', 'cn']
  },
  logLevel: {
    type: 'string',
    enum: ['TRACE', 'DEBUG', 'INFO', 
    'WARN', 'ERROR', 'FATAL']
  },
  important: {
    type: 'array',
    items:{
      type: 'string',
      enum: [
        'gamspath',
        'rpath',
        'logpath',
        'launchExternal',
        'logLifeTime',
        'language',
        'logLevel'
     ]
    }
  }
}