Rules for scenario sharing

If several users have access to the same MIRO Server app, they can share scenarios. Shared scenarios can be loaded from the database into the sandbox in the same way as your own scenarios.

• Scenarios can be shared with individual users and/or with user groups.
• Scenarios can only be shared with groups or users of a group in which you are a member yourself. Inviters can also see users in groups of invitees of which they themselves are not members. Admins can see all users and groups.
• The user who shares a scenario with others is the scenario owner. The scenario owner is displayed to other users when they load a shared scenario into their sandbox.
• Scenarios can be stored under the same name in the database if the owner is different.
• Access permissions are assigned to a shared scenario. As scenario owner you decide about who has read, write and/or execute permissions. Users with read permissions can load the owner's scenario but are not authorized to edit or execute it. The scenario is marked with a lock symbol (). Write permissions give you the right to change the scenario (data) and save it again. With execute permissions you are authorized to solve the scenario.
• It is not possible to revoke the owner's access permissions.
• Users with read access can duplicate the scenario via the "Save as" button. They become the owner of this new scenario.
• For the time a scenario is opened in MIRO, it is locked for other users. This prevents conflicts arising when a scenario is used concurrently. Locked scenarios can be opened in readonly mode by others (and also saved under a new name). A lock symbol () next to the scenario name indicates the readonly status. Users with write permissions for the scenario are additionally informed about this via a notification in the lower right corner of the screen.
  

  

Share a scenario

The information about whether a scenario should be shared with others is controlled in the 'Access permissions' tab under Scenario → Edit metadata.

Install MIRO Server

To install MIRO Server, first download the ZIP file that contains everything you need to get started here.

The general installation instructions are given below. However, keep in mind that the installation is highly dependent on your setup. The setup of GAMS MIRO Server should typically be performed by a system administrator. If you have problems with the installation, please do not hesitate to contact us by mail at support@gams.com.

• 
  Linux
• 
  Windows

Start / Stop / Update / Uninstall

This section assumes a Linux operating system. On Windows, ./miro-server must be replaced by miro-server.cmd in the commands, e,g, miro-server.cmd start.

Once you have GAMS MIRO Server installed, you can launch it via

To stop a running instance of GAMS MIRO Server, run

To perform a restart, run

To update GAMS MIRO Server to the latest version, run

To remove GAMS MIRO Server including all data associated with it from your server, run

Customize MIRO Server

After setting up MIRO Server, some basic configurations can be made. This includes, among other things, setting a logo for the login screen or adjusting the authentication method.

Most of the settings can be done in the data/application.yml file in the miro_server directory. Note that you must stay with the file's YAML format. It is also important that no adjustments are made to the file other than the following settings. Changes directly affect the functionality of MIRO Server!

application.yml example

proxy:
  title: GAMS MIRO Server
  template-path: ./templates/2col
  favicon-path: ./favicon.ico
  model-dir: ${GMS_MIRO_MODEL_DIR}
  data-dir: ${GMS_MIRO_DATADIR}
  miro-lang: en
  port: 8080
  heartbeat-rate: 10000
  heartbeat-timeout: 120000
  admin-groups: admins
  container-log-path: /logs/container-logs
  api-version: 1
  authentication: webservice
  webservice:
    authentication-url: http://auth:1234/login
    authentication-request-body: '{"username": "%s", "password": "%s"}'
    authentication-response-token: '$.token'
    authentication-response-roles: '$.roles'
  users:
  - name: admin
    password: admin
    groups: admins
  database:
    host: miroserver-db
    port: 5432
    name: ${GMS_MIRO_DATABASE}
    username: ${GMS_MIRO_DATABASE_USER}
    password: ${GMS_MIRO_DATABASE_PWD}
  engine:
    host: ${GMS_MIRO_ENGINE_HOST}
    ns: ${GMS_MIRO_ENGINE_NS}
    anonymous-user: ${GMS_MIRO_ENGINE_ANONYMOUS_USER}
    anonymous-pwd: ${GMS_MIRO_ENGINE_ANONYMOUS_PWD}
  docker:
    url: http://dockerproxy:2375
    internal-networking: true
    container-network: miroserver-network
    miro-image-name: ${GMS_MIRO_UI_IMAGE}
    admin-image-name: ${GMS_MIRO_ADMIN_IMAGE}
logging:
  file:
    /logs/miroproxy.log

spring:
  servlet:
    multipart:
      max-file-size: 200MB
      max-request-size: 200MB
   
server:
  forward-headers-strategy: native
  servlet:
    session.timeout: 21600
    context-path: /

• Title (proxy.title):
  Sets the title that is visible in the browser tab.
• Language (proxy.miro-lang):
  

  With this setting you can set the global language for all deployed MIRO apps. Currently, the languages available are English ('en'), Chinese ('cn') and German ('de'). This global language setting initially applies to all apps. You can still set a different language individually for each app, which overrides the global setting. This allows to host apps in different languages. Read more about how to change the language for an individual app.

• Authentication method (proxy.authentication):
  When you set up MIRO Server as a server administrator, you can choose to use the service with or without authentication. This decides whether anyone with access to the MIRO Server URL is allowed to access the MIRO apps, or whether GAMS Engine credentials are used. In the data/application.yml file you can change this setting. The following options are available:
  • proxy.authentication: webservice: GAMS Engine authentication
  • proxy.authentication: none: No authentication

Note that when using MIRO Server without authentication, an anonymous GAMS Engine user with at least execute permissions on the used namespace must be created. The credentials of this user must be provided in the .env file in the miro_server directory. More about this here.

• Context-path (server.servlet.context-path):
  If you want to host MIRO Server on a different path than root, you must adjust the context path under server.servlet.context-path. For example, if you want to access the MIRO apps at https://mydomain.com/miroapps, then the context-path must be set to /miroapps. Beside the adjustment of the path in the application.yml file, the configuration of the reverse proxy (Nginx: location property) has to be adjusted as well.

• Logo:
  In addition to the settings in the application.yml, the logo that is displayed in the login screen can also be customized. To change the logo, replace the logo.png and logo.svg under data/img/ in the miro_server directory.
• Color styles:
  

  The CSS styles of MIRO Server can be customized. For example, you can use predefined company colors in the login and overview screen:

  

  For this purpose, a custom CSS file must be provided when MIRO Server is started. To do this, create a new directory 'CSS' under miro_server/data, where you put the custom CSS (e.g. miro_server/data/css/styles.css). Now specify this style sheet in the docker-compose.yml file under 'volumes':

       ports:
         - 8080:8080
       volumes:
  +      - ./data/css/styles.css:/home/miroproxy/templates/2col/assets/css/styles.css
         - ./data:/home/miroproxy/data
  

  The path before the colon (./data/css/styles.css) points to the custom CSS file. The second path must not be changed.

  Note:

  Note that the styles only affect MIRO server components and not the MIRO applications themselves!

All changes will take effect after a restart of MIRO Server. If you make changes to the docker-compose.yml configuration you need to do a ./miro-server stop and ./miro-server start.

Extending the MIRO Docker image

In case your MIRO applications need additional packages, you have to extend the MIRO UI Docker image. You can do so by adding the additional packages required by your custom renderers to the file additional_packages located inside the miro_server directory. Each package name must be on a new line. Once all packages are added to this file, run

Nginx example configuration

We suggest to run GAMS MIRO Server behind a reverse proxy such as nginx. You can find an example configuration in the file miro.conf located inside the miro_server directory mentioned in the installation instructions. To apply this configuration, simply copy it to the configuration location of your nginx (e.g. sudo cp miro.conf /etc/nginx/conf.d/). Note that you will have to reload nginx afterwards using sudo nginx -s reload.

When you are hosting MIRO Engie and MIRO Server on the same host, you have to merge the nginx configurations of both GAMS Engine and MIRO Server. A resulting /etc/nginx/conf.d/miro.conf could look as follows:

Nginx example configuration

map $http_upgrade $connection_upgrade {
   default upgrade;
   ''      close;
}
server {
    listen 80;
    location / {
        proxy_pass http://127.0.0.1:8080;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 600s;

        proxy_redirect    off;
        proxy_set_header  Host             $http_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;
    }
    location /engine {
        proxy_pass http://127.0.0.1:5000;
        
        proxy_redirect    off;
        proxy_set_header  Host             $http_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;

    }
    client_max_body_size 0;
}

Note that even though both GAMS Engine and MIRO Server run on the same host, the GAMS Engine host is not localhost. In case TLS, port/certificate info etc. is used, this needs to be added here as well. If you need help with this, please contact us. Nginx needs to be reloaded if the configuration has been changed: sudo nginx -s reload.

If you want to host MIRO Server on a path other than root, you must change the context path in the file data/application.yml accordingly (entry server.servlet.context-path).

Running under SELinux

Note that with SELinux active (e.g. CentOS/RHEL), you might have to allow your nginx server to proxy to the upstream MIRO Server host. You can do so by running: setsebool -P httpd_can_network_connect 1.

User Management

The admin panel

Access

In the Admin panel of MIRO Server you can add new MIRO apps and delete existing ones. Among other things, access to individual apps can also be controlled here via a user group system.

A user with read, write and execute permissions on the namespace that MIRO Server uses will be considered as a MIRO Server administrator. As an administrator, the tabs 'Admin Panel' and 'Containers' are additionally displayed next to the 'Home' tab:

A click on Admin Panel opens a overview with all deployed apps:

How to access the admin panel when using MIRO Server without authentication:
When MIRO Server is used without authentication, there is no login screen anymore. Everyone accessing the MIRO Server landing page will end up on the library. Accordingly, there is no longer a distinction between admininistrator and normal user (i.e. there is no admin panel button). In this case you can reach the admin panel via a direct link, just like with MIRO apps. The app id is admin in this case: mydomain.com/app_direct/admin/

Add apps

As with the local MIRO Desktop library, a new MIRO app (miroapp file) can be added easily via drag & drop or by clicking on the last tile:

The dialog that opens shows a preview of the deployed app including logo, title and description, which can be modified. Note that the maximum file size for the logo is 1 mb.

Further settings that can be made before adding the app:

• Access groups (optional):
  By default, any Engine user who has access to the namespace used by MIRO Server can see all apps. To limit who is allowed to use the app you want to add, you can optionally assign access groups. A user who is not a member of one (or more) of the assigned access groups does not see the app in the app overview and cannot reach it via direct link (see an example). All GAMS Engine groups of the namespace used by MIRO Server in which the MIRO administrator is a member or has access rights are available for selection. Learn how to create groups and add users in GAMS Engine.
• App environment (JSON, optional):
  

  Here you can define a customized environment to be used by the MIRO app in JSON syntax. This can be useful/mandatory, for example, if you want to run custom analysis scripts that require external software not in the PATH or to store credentials to be used by remote data exchange modules. A detailed description including an example can be found in the MIRO Desktop documentation. The only difference to the local version is that with MIRO Server you can specify a separate environment for each app, while with MIRO Desktop this applies globally to all apps.

  While the global language setting applies to all apps, the app environment can be used to change the language of an individual app. This allows the use of apps in different languages within one MIRO Server instance. The environment variable MIRO_LANG specifies the language. Available languages currently are English ('en'), Chinese ('cn') and German ('de'). Example: {"MIRO_LANG":"de"}.

  

When all settings are done, add the app by clicking on 'Save'. The app is then validated and added to the library.

Scenario data: All scenarios that are bundled with the app are stored in the MIRO Server database. The user who adds the app will become the scenario owner. All users with access to the app have read and execute permissions for these scenarios.

Add scenario data

Besides the possibility to bundle scenario data with an app, scenarios can also be added afterwards using the 'Add MIRO scenarios' box:

Scenario files can be added here. The following rules apply:

• Scenarios must be in miroscen format.
• Only one scenario can be added at a time.
• The scenarios must match a MIRO app that is already deployed on MIRO Server.
• Scenarios are assigned to the user who adds them.
• The scenarios are made available (read and execute permissions) to all users who have access to the app.

Access MIRO apps

MIRO Server library

The landing page of MIRO Server shows the MIRO Server library. It lists all apps that a user has access to and is very similar to the app library of MIRO Desktop. Each app is displayed in a separate tile and can be launched from there:

Controlling app access

If several MIRO apps are used, it may make sense to make certain apps accessible only to certain users. There are two possible ways to do this.

User Groups

In GAMS Engine users can be assigned to groups (read more about user groups in the GAMS Engine documentation). These groups can be used to control who can see which MIRO app hosted on MIRO Server. In the following example, there are three groups A, B and C. Users in group A have access to 4 apps, users in group B have access to 3 other apps. Group C users can access 2 apps, one of which is also used by another group.

All users access MIRO Server via the same URL. However, as a member of a group, you don't see anything from other apps from other groups.

Tip:

A user can also be a member of multiple groups.

Creating user groups and assigning users to them is done quickly. So it's very easy to control who can access which apps with this approach.

• Learn how to create groups and add users in GAMS Engine
• Learn how to control which group can see which app on MIRO Server.

Multiple MIRO Server instances

In this approach, users are separated from each other not by groups, but by separate MIRO Server instances. The example setup is as follows: There are 3 different MIRO Server instances, each accessible under a different URL. The MIRO server instances all access the same GAMS Engine instance, but use different namespaces. Using groups is of course still possible, but not necessary in this example.

Note:

Note that in this setup it is not possible to share individual apps with multiple groups. Apps have to be added and maintained separately in each MIRO Server instance. Except that they use the same GAMS Engine, the three instances have nothing to do with each other.