GAMS Engine One is our single-node job and user management solution for running GAMS optimization models on your own hardware, whether on-premise or in the cloud. It provides a Docker-based installation managed via a Docker Compose stack.

You can download the latest Engine One installation scripts here. The general installation instructions are given below. However, keep in mind that the installation is highly dependent on your setup. Since 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, please do not hesitate to contact us by mail at support@gams.com.

For more information about the third-party software included in Engine and their licenses, see here.

• Install Docker from https://docs.docker.com/engine/install/. Start docker afterwards. We further recommend to configure Docker to start on boot.
• 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 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.
    Note:

    Note that when using network licenses -u must be set to y!

  • -m: Mount path (optional)
    By default, 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.
  • -C: CPU limit/reservation for worker containers (e.g., '0.5'), as number of cores (optional).
  • -M: Memory limit/reservation for worker containers (e.g., '512m'). Supported are kb (kilo bytes), mb (mega bytes) and gb (giga bytes) (optional).

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

Start

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

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

Update

To update GAMS Engine to the latest version, simply execute the ./up.sh script from the same directory where you originally installed Engine, with the same arguments you used when you installed GAMS Engine.

NOTE: A warning may be displayed during the update that databases need to be upgraded. Read here for more information about how to upgrade databases.

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

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

Certain GAMS Engine releases (see release notes) will upgrade the internal databases (PostgreSQL, MongoDB, RabbitMQ) for performance and security.

When you update GAMS Engine using the ./up.sh script, a warning will be displayed if a database upgrade is required. The upgrade will typically continue, and GAMS Engine will still work with the old database versions, but we highly recommend that you upgrade as soon as possible.

The upgrade is as easy as running the ./upgrade-db.sh script, which is placed inside your Engine installation directory after updating.

If the upgrade was not successful, you can roll back easily.

Once the upgrade has been successful and you have thoroughly checked that everything is working, you may want to perform a cleanup to free up disk space.

Rollback

The Docker volumes of the old databases are not removed. Rolling back in case of a failed update is as easy as replacing the docker-compose.yml file in your Engine installation directory with the backup file: docker-compose.yml.pre-upgrade-bak.

Cleaning Up Old Volumes (Optional)

After a successful upgrade, the old Docker volumes are kept to allow for rollback. Once you have verified that the new version is working correctly, you can reclaim disk space by removing them.

Warning: This is permanent and prevents easy rollback.

The upgrade-db.sh script will print the exact command to run for cleanup at the end of a successful upgrade.

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 Administration section by clicking on the corresponding buttons.

There are two forms of Engine licenses: USI based licenses and normal licenses (the sales team can tell you what type of license is best suited for you). USI based 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 (this step is not required for normal licenses). As a last step, paste the license key you received into the field (2) and click on the Update button (3).

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.

GAMS Engine K is our enterprise-grade job and user management system for running GAMS optimization models on Kubernetes. It is built for high-demand environments that require maximum scalability, flexibility, and resilience.

• Deployment: Deployable to on-premise or cloud-based Kubernetes environment, easily installed and managed via Helm charts.
• Precision Scaling: Supports heterogeneous workers. Users can request specific CPU and RAM resources for a particular job, ensuring heavy models get the power they need while smaller jobs stay lean.
• Governance: Administrators can set granular limits, controlling exactly how many resources specific users or groups can request.

GAMS Engine can be installed on a Kubernetes cluster using our official Helm Chart. The source code and configuration files for the chart are available in our Helm Chart Repository. Before installing Engine K, ensure your environment meets the necessary requirements.

Installing the Helm Chart

To install the chart with the release name my-engine into a new namespace called gams:

# 1. Add the GAMS Helm repository
helm repo add gams https://charts.gams.com/
helm repo update

# 2. Install the chart
helm install my-engine gams/gams-engine -f my-values.yaml --namespace gams --create-namespace

Retrieving Generated Passwords

By default, the Helm chart automatically generates secure passwords for Engine K. After the installation is complete, you can retrieve these credentials from the generated Kubernetes secret.

To view the secret for your my-engine release in the gams namespace (to retrieve the plaintext passwords afterwards echo "ENCODED_STRING" | base64 --decode):

Network Policies

Network Policies in Kubernetes act as an internal firewall, ensuring that pods only communicate with authorized pods and resources.

The Engine K Helm chart comes with strict Network Policies enabled by default. If your cluster's CNI (Container Network Interface) does not support them, or if you prefer to manage them externally, you can toggle them off in your custom values.yaml:

global:
  # Set to false to disable default network policies
  useNetworkPolicies: true

If you keep them enabled but need to allow Engine components to communicate with outside services, you can add extraEgress or extraIngress rules to specific components that allow this feature. For configuration settings, please refer to values.yaml.

If you use network licenses, you must allow your workers (pods that run your GAMS jobs) to access internet or configure an on-prem GAMS license server and give your workers access to that license server. You can grant this access by adding custom egress rules to the jobSpawner configuration in your custom values.yaml:

jobSpawner:
  workerNetworkPolicy:
    extraEgress: []

Accessing the Engine UI

All communication with Engine K is routed through the Broker component, which hosts both the Engine API and the web-based Engine UI.

For a demonstration or local testing, you can immediately expose the UI using port-forwarding:

This will make Engine UI available at http://localhost:8080 . You can then log in by following the instructions provided in the Helm welcoming message. Once you have successfully logged into the Engine UI, you must change your admin password.

Production Ingress Configuration

For production environments, we highly recommend utilizing an Ingress controller. You can enable and configure this directly in your custom values.yaml. Here is a standard example using NGINX:

ingress:
  enabled: true
  ingressClassName: "nginx"
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
  path: /
  pathType: "Prefix"
  hosts:
    - engine.yourcompany.com
  tls:
    - hosts:
        - engine.yourcompany.com
      secretName: chart-example-tls

For further details, please refer to the Helm Chart repository.

For comprehensive instructions on administration and management, please refer to Administration.