Installation & Licensing

Installation

You can download the latest GAMS Engine installation scripts here. The general installation instructions are given below. However, keep in mind that the installation is highly dependent on your setup. Since GAMS Engine is a server application, the concepts of ports, SSL, certificates, etc. are omnipresent. Setting up such a system is a common task for a server administrator. If you have problems with the installation of GAMS Engine, please do not hesitate to contact us by mail at support@gams.com.

  • Install Docker from https://docs.docker.com/engine/install/. Start docker afterwards. We further recommend to configure Docker to start on boot.
  • Install Docker Compose from https://docs.docker.com/compose/install/.
  • Extract gams_engine.zip. This will create a subfolder gams_engine.
  • Open a terminal and cd into that folder.
  • Run the script ./up.sh with admin privileges. The following arguments can be used:
    • -a: Admin password (optional)
      The password of the admin user. By default, admin is used. If GAMS Engine is exposed to the Internet, it is recommended to install Engine with a different password so that there is no time window for logging in and changing the default password.
    • -p: Engine port (optional)
      If no certificate files are provided (see below), this option can be used to specify the port through which you want to reach Engine. Port 80 is used per default. For the encrypted setup (certificate files are provided), port 443 is always used.
    • -w: Number of workers
      Specifies how many GAMS workers should be enabled, i.e. how many GAMS jobs Engine should process in parallel. If all GAMS workers are occupied, incoming jobs are queued and started as soon as workers are available again.
    • -c: Certificate file (optional)
      For the SSL setup, the path to the certificate file must be specified here.
    • -k: Certificate key file (optional)
      For the SSL setup, the path to the certificate key file must be specified here.
      Note:

      Note that when using the encrypted setup, port 80 and port 443 must be available!

    • -u: worker container access internet y or n (optional, default: n ).
      By default, workers are not allowed to access the Internet for security reasons. If you want to change this, you can specify y and workers can access the Internet.
    • -m: Mount path (optional)
      By default, GAMS Engine is mounted under /. To change this, specify the mount path here (e.g. -m engine to mount the UI on /engine and the API on /engine/api). Note that there must not be a leading slash in the mount path specification.

    The script downloads and initializes all required Engine files. This may take a moment.

  • Install Docker from https://docs.docker.com/engine/install/ (note the system requirements). Start docker afterwards. We further recommend to configure Docker to start on login.
  • Extract gams_engine.zip. This will create a subfolder gams_engine.
  • Open a terminal and cd into that folder.
  • Run the script .\up.cmd. The following arguments can be used:
    • /a: Admin password (optional)
      The password of the admin user. By default, admin is used. If GAMS Engine is exposed to the Internet, it is recommended to install Engine with a different password so that there is no time window for logging in and changing the default password.
    • /p: Engine port (optional)
      If no certificate files are provided (see below), this option can be used to specify the port through which you want to reach Engine. Port 80 is used per default. For the encrypted setup (certificate files are provided), port 443 is always used.
    • /w: Number of workers
      Specifies how many GAMS workers should be enabled, i.e. how many GAMS jobs Engine should process in parallel. If all GAMS workers are occupied, incoming jobs are queued and started as soon as workers are available again.
    • /c: Certificate file (optional)
      For the SSL setup, the path to the certificate file must be specified here.
    • /k: Certificate key file (optional)
      For the SSL setup, the path to the certificate key file must be specified here.
      Note:

      Note that when using the encrypted setup, port 80 and port 443 must be available!

    • /u: worker container access internet y or n (optional, default: n ).
      By default, workers are not allowed to access the Internet for security reasons. If you want to change this, you can specify y and workers can access the Internet.
    • /m: Mount path (optional)
      By default, GAMS Engine is mounted under /. To change this, specify the mount path here (e.g. \m engine to mount the UI on /engine and the API on /engine/api). Note that there must not be a leading slash in the mount path specification.

    The script downloads and initializes all components required for GAMS Engine. This may take a moment.

  • Once the script is finished, GAMS Engine should be running. Depending on whether the SSL or the unencrypted setup has been selected, Engine and Engine UI can be reached via:
    • SSL setup: Open http(s)://mydomain.com in your browser (replace mydomain with your URL).
    • Unencrypted setup: Engine runs on the port you selected before (default is port 80). Open http://192.168.178.184:80 in your browser (replace IP and port accordingly).

    • This will open the Engine UI. Login with the default credentials username: admin and password: admin.

Stop / Update / Uninstallation

Start

To start a stopped instance of GAMS Engine, navigate to the directory where you installed GAMS Engine and execute

> docker-compose up -d --scale worker=<number_workers>

where <number_workers> is the number of workers you want to run in parallel.

Stop

To stop a running instance of GAMS Engine, navigate to the directory where you installed GAMS Engine and execute

> docker-compose down

Update

To update GAMS Engine to the latest version, simply execute the ./up.sh script (or .\up.cmd if you are working under Windows) with the same arguments used to install GAMS Engine.

Uninstall

To remove GAMS Engine including all its data (this data will be lost if you did not make backups!) from your server, navigate to the directory where you installed GAMS Engine and execute

> docker-compose down -v

Additionally, you can remove the directory where you extracted the GAMS Engine configuration files.

Licensing

General

For a GAMS Engine setup, both a tailored GAMS license and an Engine license are required. The license keys can be entered directly in the Engine UI in the Users section by clicking on the corresponding buttons.

Providing Engine and GAMS license keys

Engine licenses are tied to a particular Engine installation. An Engine installation is identified by a so-called Unique System Identifier (USI). You can find the USI by clicking on the Update Engine license button. A new dialog for updating your Engine license opens. The USI is located at the top of the dialog (1). Please send this identifier to sales@gams.com to receive your license key. As a last step, paste the license key you received into the field (2) and click on the Update button (3).

Providing Engine license

A GAMS license can be specified system-wide or user-specific.

  • System-wide means that all users of the running Engine instance use the same license when solving their GAMS models. The system-wide license can be entered at the top of the page via the Update GAMS license button, right next to the Update Engine license button.
  • A user-specific GAMS license is only valid for the individual owners of the license. If a user has such a license, this will always be used for GAMS jobs instead of the system-wide license. Also, if an inviter with such a license invites another person to use GAMS Engine, the invitee automatically inherits the license of the inviter.
    User licenses are entered in the user list under Actions → Update license.

Gurobi license

If you want to use the Gurobi solver, you must provide Engine with the Gurobi license. This license must be either a Web License Service (WLS) license, a license for a Gurobi Compute Server, a Gurobi Cloud license, or a license from a Gurobi Token Server. Standard Gurobi license types (NODE, Academic) do not work with Engine.

To use Gurobi with Engine, you must first generate a Gurobi client license file (gurobi.lic) and place it in your Engine directory. You also need to generate a short gamsconfig.yamlfile with the following content:

environmentVariables:
   - GRB_LICENSE_FILE:
      value: /etc/gurobi.lic

This file should also be located in your Engine directory.

As a final step, open the docker-compose.yml file with a text editor and modify it as follows:

  worker:
    image: gams/engine-worker:latest
    restart: unless-stopped
[...]
+   volumes:
+     - ./gurobi.lic:/etc/gurobi.lic
+     - ./gamsconfig.yaml:/etc/xdg/GAMS/gamsconfig.yaml
    networks:
      - worker-network
+     - worker-ext-network

Note that we have added the worker-ext-network network to the worker containers. This causes the worker containers to be able to access the external network, which is required for Gurobi to contact the license server.

For these changes to take effect, restart the GAMS Engine.