Installation & Licensing

Installation

When you purchase GAMS Engine, you will receive a ZIP file that contains everything you need to get started. 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:
    • -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!

    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:
    • \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!

    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

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, navigate to the directory where you installed GAMS Engine and execute

> docker-compose pull

This will pull the latest images from Docker Hub. Once the images are pulled, run

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

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

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. For the Engine license, click on the Update Engine license button at the top of the page and enter the key.

Providing Engine and GAMS license keys

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.