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

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

GAMS MIRO Server will now listen on port 8080 and the MIRO Server REST API on port 8081 . You can log in with any GAMS Engine user who either has some permission or can see models in the specified namespace. Users without permissions in the namespace can see a model if they can see a user group associated with that model.

To directly access a MIRO application that has been added to MIRO Server, go to /app_direct/<appId>, where appId is the lowercase name of your main gms file per default.

To stop a running instance of GAMS MIRO Server, run

To perform a restart, run

Note that if you make changes to the docker-compose.yml file these changes are not reflected after running this command. In such a case do a ./miro-server stop and ./miro-server start.

To update GAMS MIRO Server to the latest version, run

Note that this will pull new images from Docker Hub and launch them. If you only want to pull new images, run

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

Additionally, you can remove the directory where you extracted the configuration files of the GAMS 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
  theme: forest
  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
  force-signed-apps: false
  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: /

The following settings can be made in the data/application.yml file:

• Title (proxy.title):
  Sets the title that is visible in the browser tab.
• Color theme (proxy.theme): For MIRO Server the same color themes are available as for MIRO Desktop:
  • Default theme (YAML value: "default")
  • Black and white ("blackandwhite")
  • Green forest ("forest")
  • Tawny ("tawny")
  • Dark blue ("darkblue")
  • Red wine ("redwine")

  This global color theme setting initially applies to all apps, the app overview page and the login screen. You can set a different color theme individually for each app, which overrides the global setting. Read more about the app environment here.

  Note that in addition to the predefined themes, you can also include a customized css file.

• 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.

• Force apps to be signed (proxy.force-signed-apps):

  MIRO apps can be signed to guarantee the authenticity of the developer. This can protect you from accidentally importing apps that have been tampered with by a malicious actor. By default, MIRO Server imports all apps. No signature verification is enforced. To enable signature verification, set this option to: true. MIRO will then issue an error in case you try to import an app that is not signed by a trusted developer. You should store all public keys (in PEM format) of the developers you trust in the directory: miro_server/data/known_keys.

• 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

When running MIRO Server without authentication, models can only be solved/submitted to GAMS Engine if a user with execute permissions is used. 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. Note that this has no effect on the MIRO Server REST API. To also change the root path of the REST API, you must specify the root path via the SCRIPT_NAME environment variable in the docker-compose.yml file:

  auth:
    image: miro-auth
    build: ./auth/
    ports:
      - 8081:1234
    environment:
+     SCRIPT_NAME: /miroapps
      PORT: 1234

Other settings:

• 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.
• Custom 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.

  The default stylesheet used by MIRO Server can be found here.

  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.

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

(on Windows miro-server.cmd build). Please note that additional packages may cause version conflicts with packages used internally by MIRO. We therefore recommend keeping the number of additional packages to a minimum.

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;
}
# redirect all http to https (optional)
#server {
#    listen 80;
#    return 301 https://$host$request_uri;
#}
server {
# SSL setup (optional)
#    listen 443 ssl;
#    ssl_certificate /path/to/certificate/file.pem;
#    ssl_certificate_key /path/to/key/file.key.pem;
    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 /api {
        proxy_pass http://127.0.0.1:8081;

        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/engine;

        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).

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.