This page provides a step-by-step guide on how to install the Simonstrator Platform and execute your first simulations. If you do not already have an account for our development repositories, start by registering at our GitLab instance. You can self-activate your account through a link sent to you via e-mail. Once you are logged in, you can access the publicly available parts of the platform through the @simonstrator group. For full access to all Simonstrator projects, please request membership in the @simonstrator group by clicking the respective link on the group’s homepage.

Configuration Window

To follow this guide, you do not need to request access to the @simonstrator group. However, you need to have an account at our GitLab instance.

Installing the Simrunner

The Simrunner takes care of executing simulations on top of the Simonstrator Platform. It contains the workload logic for specific simulations and application-specific analyzers to assess the performance of the system under test. The system under test itself is contained in the Overlays project, but we will come to that in a minute.

Start by cloning the SimRunner repository. When cloning via HTTPs, you will be asked for your gitlab username and password. You may chose to clone using ssh, which requires prior key setup.

# via HTTPs (no prior setup required)
git clone
# via SSH (key setup required)
git clone

This will create a simonstrator-simrunner folder containing the SimRunner Java project and a set of additional folders and configuration files. To build the project, simply execute the Maven build command in the simonstrator-simrunner folder. You might need to specify a Java-8 home, if the mvn package command fails with invalid target release: 1.8:

# (optional)
export JAVA_HOME='/usr/lib/jvm/java-8-oracle/jre'
# build the project
mvn package

Move the generated target/guirunner.jar into the root folder of the project:

mv target/guirunner.jar ./

Note, that the generated jar would need to be recompiled every time you change code in the Simrunner project. Therefore, after you are done with this quick-start guide, you should setup a full development environment as described in the installation section.

Starting a simulation

With the generated guirunner.jar in the root folder of the Simrunner project, simple start the jar from the command line:

java -jar guirunner.jar

A window opens allowing you to select the desired launch configuration:

Configuration Window

Select the lbs_vis.xml as shown in the screenshot, and click Start Simulation. After a short while, the topology visualization, a live metrics panel, and a progress view will open.

The topology visualization of the Simonstrator Live metrics window Window showing the simulation progress
Topology visualization, live metrics panel, and progress view.

Congratulations, you just executed your first simulation using the Simonstrator Platform! If you decide to start extending the Simonstrator or using it for your own projects, please continue by installing the full project environment as described on the next page.