Tramola Runners

Table of contents

Introduction
Configuring the default runners
Adding additional runners
1. Runner types

Introduction

Tramola needs to execute scheduled simulations as well as (post-)processes files it manages. To execute these tasks, so-called “Runners” are used. A runner is a small piece of software which executes these tasks on Tramola’s behalf. The advantage of using runners over Tramola executing the tasks directly is that the runners can run on difference machines, thus distributing the work-load.

Tramola integrates and starts two runners default, so that it works out-of-the-box. The first runner is reserved for internal jobs (e.g. post-processing uploaded files and simulations), while the second runner is able to execute smaller MATSim simulations.

Additional runners can be added, and the default runners can be switched off if so desired.

Configuring the default runners

To change the configuration of the included local runners, copy the following lines to your tramola.conf and modify the settings as needed. At first, you might mostly change the cpu and memory settings of the local runners:

tramola {
	localRunner = [
		{
			name = "system_jobs"
			type = "LOCAL"
			keepFiles = false
			cpu = 2
			memory = 3.0
			tags = ["jvm"]
		},
		{
			name = "MATSim"
			type = "LOCAL"
			keepFiles = false
			cpu = 2
			memory = 11.0
			tags = ["jvm", "user"]
		}
	]
}

Adding additional runners

First, go to Settings > Runners and create a new Runner Token. Next, download the runner.jar to the computer you want the runner to use. Then, start the runner with the following command:

java -jar tramola-runner.jar -h tramola.example.com \  
-p 8433 -c 4 -m 20 -e LOCAL -t TOKEN -d data

This starts a runner with 4 CPUs and 20 GB of Memory, connecting to tramola.example.com on port 8443 with the provided token and name, and using data as directory for storing any files.

The runner supports additional options. Run java -jar tramola-runner.jar --help to see the full list of all available options:

Option	Argument	Default Value	Description
`-h`	host	`localhost`	The server (host) to connect to, either a fully qualified domain name or an IP address.
`-p`	port	`3471`	The port to connect to.
`-s`	use-tls	`true`	Use TLS (i.e. https) to connect to Tramola.
`-d`	directory	`./data`	The directory to store files for the executed tasks.
`-c`	cpus	`2`	Number of CPU cores to use to run jobs.
`-m`	memory	`24`	Amount of memory (RAM) in GB to use to run jobs.
`-t`	token		The runner token to identify to the server.
`-f`	file-token		A file containing the token, instead of specifying it with `-t`.
`-n`	name	localhost’s name	The name of the runner.
`-k`	keepFiles	false	If set to true, job files will not be deleted after jobs ended. Note that enabling this feature might use large amount of storage space and should only be used for debugging.
`-e`	executor	`LOCAL`	Can bei either `LOCAL` or `DOCKER`.
`-x`	tags	jvm,user	Tags for the runner. `jvm` denotes runners which provide a JVM to run jobs, `user` denotes runners that can run user-jobs (i.e. MATSim simulations), `untrusted` if the runner is allowed to run untrusted code.

To stop an external runner, just press Ctrl + C or stop the process otherwise.

Runner types

Tramola runners currently support two different execution strategies:

LOCAL: Jobs are run as local processes. This type should only be used if you run only trusted code (e.g. only default MATSim releases or versions you created yourself), as malicious code could read arbitrary files on your system depending on the user rights the runner runs with.
DOCKER: Jobs are run inside Docker containers. Requires that docker is installed on your system. This provides an additional level of security when running user-provided MATSim JARs that contain untrusted code, as jobs can only access files within the docker image and the mounted directory containing the job files.
To support executing user-provided JAR files, add the tag untrusted to a runner. Be very cautious when to use this.