Runtime Installation and Configuration Guide

Pre-requisites for Installation

In order to execute Stambia Runtime, your system must meet the following requirements:

Operating System:
- The Runtime can be installed on any system having a Java Virtual Machine (JVM)

Memory / CPU
- The memory and CPU capacity required will depend on the flows that are executed

Disk Space
- The system must have at least 80 MO of free disk space

Java Virtual Machine
- Java 8 or Java 11

Note: On a 64-bits system you should use a 64-bits JVM for better performance and compatibility.

Runtime installation

Installing the Runtime

Preliminary steps

1. Install a Java Virtual Machine (JVM) 8 or higher
2. Set the environment variable STAMBIA_JAVA_HOME to the folder situated located just before the “bin” folder in your JDK

Runtime Installation

1. Unzip the archive which has been downloaded into the target folder
2. Set execution permissions on the script files which are at the root of the installation if needed
   1. on the .bat files for Windows
   2. on the .sh files for Linux
3. Set write permissions, especially on the following directories:
   1. temp
   2. build
   3. sessions
4. Configure the Runtime if necessary
5. Configure the Runtime’s Scheduler if necessary

Note: In order to ease updates, it is recommended to copy the Stambia ‘properties’ folder into another place and to set the parameters of the STAMBIA_PROPERTIES_LOCATION variable so that it points to it. In this way, Runtime updates can be made by replacing the whole arborescence. The configuration data of the ‘properties’ folder will not be lost, since it will be elsewhere.

Runtime as a Windows service

Service installation

To install a Runtime as a Windows service, refer to the standard installation procedure to install the Runtime, and then follow the following additional steps.

The runtime can be easily installed as a Windows service if needed.
For this, navigate to the root directory of the Runtime and use the following commands:

1. use the installEngineAsService.bat -i [<serviceName>] command to install the service
2. use the installEngineAsService.bat -r [<serviceName>] command to remove the service

The <serviceName> parameter can be useful to install multiple Runtimes on the same machine.
If not set the service will be named ‹Stambia Runtime›.

The file «stambiaEngine.conf» which is in the folder external\stambiaService\conf can be used to configure some of the service’s properties. By default, it is not useful to modify this file.

Warning: Depending on the configuration of the operating system, it is usually required to execute those commands in a command prompt started as system administrator to be able to install services

Warning: Any modification of Stambia Runtime files or parameters (in “properties” or in the ‘.bat’ files) requires the removal and reinstallation of the Windows service, so that these modifications may be taken into account.

Tip: The specified user used to launch the Runtime (Windows service) should be changed to a user with network abilities, usually a domain user.

Runtime as a Linux service

Service installation

To install a Runtime as a Linux service, refer to the standard installation procedure to install the Runtime, and then refer to the documentation of your Linux environment to find how to install a service in it.

The startup script of the Runtime is 'startengine.sh'
The shutdown script of the Runtime is 'stopengine.sh'

Those are the two scripts to manage in the Linux service / in the Linux startup shutdown processes.

Runtime configuration

Overview

There are several entry points to configure the Runtime:

• Environment variables for startup options
• Runtime configuration file
• Scheduler configuration file

Environment variables

The following optional environment variables may be defined to override default settings:

You can define your own additional variables if you want to externalize some configuration.

You can find examples of customized configuration file with additional environment variables in properties/samples/enginesParameters folder.

This is useful if you want to have everything defined through environment variables, to deploy docker images for instance.

Runtime configuration file

Overview

Most of Runtime’s configuration is done in the properties/engineParameters.xml file

This file allows to manage:

• The engine parameters (such as started services, listening ports, ...)
• The security of the Runtime (hostname and user / password restriction, roles)
• The repositories where the deliveries are stored
• The Java additional options to add at Runtime’s startup
• The log database configuration

On a default installation this file is located at the following path:

<runtime_installation_folder>/properties/engineParameters.xml

Modify this file if you want to configure the Runtime.

You can change the location of this file through environment variables, as explained in previous section.

Defining the started services

The services exposed by the Runtime, such as the scheduler, the SOAP component, or the internal Java database can be turned off if needed.
By default, they are all launched at the Runtime’s startup.
To specify which services should be started:

1. Open the engineParameters.xml file
2. Update the parameters accordingly to your needs.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="launchSchedulerEngine" value="true"/>
		<parameter name="launchExecutionEngine" value="true"/>
		<parameter name="launchReportEngine" value="true"/>
		<parameter name="startInternalDb" value="true"/>
		<parameter name="startSoapServer" value="true"/>
		<...>
	</engineParameters>
	<...>
</parameters>

The following parameters are available:

Defining the services ports

The services exposed by the Runtime are running on defined port, that can indeed be modified easily.

1. Open the engineParameters.xml file
2. Update the following parameters accordingly to your needs.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiPort" value="42000"/>
		<!--<parameter name="rmiCallbackPort" value="42000"/>-->
		<parameter name="internalDbTcpPort" value="42100"/>
		<parameter name="internalDbWebPort" value="42101"/>
		<parameter name="soapServerPort" value="42200"/>
		<...>
	</engineParameters>
	<...>
</parameters>

Defining the log database

The Runtime stores the information about sessions' execution in a log database.
This database is by default an internal H2 database, that is shipped with the Runtime and started with it.

This offers a ready-to-go environment that can be used immediately.
We however recommend changing it to a more robust database such as Oracle, Microsoft SQL Server (MSSQL), etc for production use.
You will need to provide to Stambia Runtime a user having read and write permissions on the chosen database/schema.

Here is how to change the log database of the Runtime:

1) Open the engineParameters.xml file
The configuration is performed in this file, which contains samples for the most known databases.

2) Modify the log database parameters as explained below.
This consists of defining the JDBC URL, user, password, schema, Module, ... which define where the log database will be located and how to connect.

3) Restart the runtime
All necessary tables will be created automatically the first time the log database is initialized

Warning: For the Runtime to be able to communicate with the database, except if you are using the default internal H2 database, you must define in the configuration a valid Module containing the required drivers (such as JDBC drivers). The Module to use is defined through the Module parameter.

Log database parameters

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="userLogDefaultName" value="logDatabase"/>
		<parameter name="defaultSessionLogLevel" value="400"/>
		<...>
	</engineParameters>
	<...>
	<logs>
		<...>
		<log userLogName="logDatabase" autoUpdate="true" userLogClass="com.indy.engine.userLog.RdbmsUserLog">
			<parameter name="userLogRdbmsDriver" value="org.h2.Driver"/>
			<parameter name="userLogRdbmsUrl" value="jdbc:h2:tcp://localhost:42100/sessions/internalDb/sessionLogs"/>
			<parameter name="userLogRdbmsUser" value="sa"/>
			<parameter name="userLogRdbmsPassword" value=""/>
			<!--<parameter name="userLogRdbmsEncryptedPassword" value=""/>-->
			<parameter name="userLogRdbmsModule" value="internal"/>
			<parameter name="userLogRdbmsVarcharType" value="varchar"/>
			<parameter name="userLogRdbmsVarcharMaxSize" value="1000"/>
			<parameter name="userLogRdbmsNumericType" value="numeric"/>
			<parameter name="userLogRdbmsClobType" value="clob"/>
			<parameter name="userLogRdbmsBlobType" value="blob"/>
			<parameter name="userLogRdbmsSchemaName" value="logs"/>
			<parameter name="userLogRdbmsUseSchemaNameForIndexCreation" value="true"/>
			<parameter name="userLogRdbmsDeleteSyntaxe" value="Delete from"/>
			<!--<parameter name="userLogRdbmsTablePrefix" value="STB_LOG_"/>-->
			<!-- bestCompression / bestSpeed / default-->
			<parameter name="userLogRdbmsCompressedLevel" value="bestCompression"/>
			<!-- text / binary / compressed-->
			<parameter name="userLogRdbmsDeliveryFormat" value="compressed"/>
			<parameter name="userLogRdbmsPropertyMaxVarcharSize" value="1000"/>
			<!-- -1 : infinite -->
			<parameter name="userLogRdbmsPropertyMaxClobSize" value="10000"/>
			<!-- binary / compressed-->
			<parameter name="userLogRdbmsPropertyBinaryFormat" value="compressed"/>
			<parameter name="userLogRdbmsTimestampQuery" value="select now()"/>
			<parameter name="userLogRdbmsInactivityDetectionPeriod" value="90000"/>
			<parameter name="userLogRdbmsActivityRefreshInterval" value="60000"/>
			<parameter name="userLogRdbmsDeletionWithNotExists" value="true"/>
			<!--<parameter name="userLogRdbmsIndexCreationOption" value=""/>-->
			<!--<parameter name="userLogRdbmsTableCreationOption" value=""/>-->
			<parameter name="userLogRdbmsConnectionRetryNumber" value="10"/>
   			<parameter name="userLogRdbmsConnectionRetryDelay" value="2000"/>
   			<parameter name="userLogRdbmsConnectionEnableRetry" value="true"/>
		</log>
		<...>
	</logs>
	<...>
</parameters>

User Log Default Name

The «userLogDefaultName» is used to define which configured log database should be used.
This corresponds to the «userLogName» attribute which can be found in the log database configuration nodes(<log></log> nodes)

Default Session Log Level

The «defaultSessionLogLevel» defines what level of information is logged inside log database for each session executed by the Runtime.
The higher the value is the higher information are logged.
Possible values are the following: -1, 0, 100, 200, 300, 400

Note that is applies only for sessions on which the log level is not defined manually at execution.
Refer to the runtime parameters reference part of this documentation for details information about each value.

Log part

This is the part where you will configure the JDBC URL, user, password, schema, Module, ... to connect to the log database.
All necessary tables will be created automatically the first time the log database is initialized.
The initialization is performed the first time the Runtime is started on this log database.

Under <logs></logs> node, you can find commented examples of configuration for several databases systems.
You can use these examples to configure your log database accordingly to the target database system which will be used.

The Runtime will use as log database the <log></log> node which «userLogName» attribute value corresponds to the «userLogDefaultName» parameter value.

If you uncomment the examples nodes to, you’ll therefore have to be careful to keep only one <log></log> node which «userLogName» attribute value corresponds to the «userLogDefaultName» parameter value.

Warning: For the Runtime to be able to communicate with the database, except if you are using the default internal H2 database, you must define in the configuration a valid Module containing the required drivers (such as JDBC drivers). For instance, if you are using Oracle as log database, you must use a Module in which you have added Oracle’s JDBC driver. The Module to use is defined through the Module parameter.

Example

The example below is for an Oracle database.

You should at least define / verify those parameters.

• userLogRdbmsUrl
• userLogRdbmsUser
• userLogRdbmsPassword
• userLogSchemaName
• userLogRdbmsModule

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="userLogDefaultName" value="logDatabase"/>
		<parameter name="defaultSessionLogLevel" value="400"/>
		<...>
	</engineParameters>
	<...>
	<logs>
		<...>
		<log userLogName="logDatabase" autoUpdate="true" userLogClass="com.indy.engine.userLog.RdbmsUserLog">
			<parameter name="userLogRdbmsDriver" value="oracle.jdbc.driver.OracleDriver"/>
			<parameter name="userLogRdbmsUrl" value="jdbc:oracle:thin:@[host]:[port]:[sid]"/>
			<parameter name="userLogRdbmsUser" value="[USER]"/>
			<parameter name="userLogRdbmsPassword" value="[PASSWORD]"/>
			<parameter name="userLogRdbmsModule" value="[MODULE_NAME]"/>
			<parameter name="userLogRdbmsSchemaName" value="[SCHEMA_NAME]"/>
			<parameter name="userLogRdbmsVarcharType" value="varchar2"/>
			<parameter name="userLogRdbmsVarcharMaxSize" value="4000"/>
			<parameter name="userLogRdbmsClobType" value="clob"/>
			<parameter name="userLogRdbmsBlobType" value="blob"/>
			<parameter name="userLogRdbmsNumericType" value="number"/>
			<parameter name="userLogRdbmsDeleteSyntaxe" value="Delete from"/>
			<parameter name="userLogRdbmsDeliveryFormat" value="text"/>
			<parameter name="userLogRdbmsPropertyMaxVarcharSize" value="1000"/>
			<parameter name="userLogRdbmsPropertyMaxClobSize" value="10000"/>
			<parameter name="userLogRdbmsPropertyBinaryFormat" value="compressed"/>
			<parameter name="userLogRdbmsConnectionRetryNumber" value="10"/>
			<parameter name="userLogRdbmsConnectionRetryDelay" value="2000"/>
			<parameter name="userLogRdbmsConnectionEnableRetry" value="true"/>
		</log>
		<...>
	</logs>
	<...>
</parameters>

Note: Refer to the ‹Runtime parameter reference› part of this documentation for the list of all available parameters with explanations.

Disabling the log database

It is possible to use the Runtime without connecting to a log database.

For the Runtime to not have any log database, you can simply not define any logs nodes inside Runtime configuration file. You can remove or comment the existing <logs></logs> nodes.

Moreover, you can also define explicitly that you do not want the Runtime to use a log database by defining a log node with the «EmptyUserLog» class. This is more declarative if you prefer to control what is inside the configuration file and if you want to avoid relying on default behaviour.

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="userLogDefaultName" value="logDatabase"/>
		<...>
	</engineParameters>
	<...>
	<logs>
    	<log userLogName="logDatabase" autoUpdate="false" userLogClass="com.indy.engine.userLog.EmptyUserLog">
        </log>
	</logs>
	<...>
</parameters>

Defining Delivery Repositories

Repositories are the locations where the Runtime will look for the delivery files at execution.

About Delivery Repositories

Delivery Repositories are the locations where the Runtime will look for the delivery files at execution.

There are different Delivery Repositories plugins, allowing to store deliveries locally on the local file system, allowing to store the deliveries remotely on Analytics, and more...

Each Delivery Repository plugin has its own way to store and retrieve deliveries, depending on your requirements.

Common configuration

Delivery repositories are configured in Runtime Configuration File (engineParameters.xml).

They are defined as follow.

<parameters>
	<...>
	<repositories>
		<...>
		<deliveryRepository name="repository_name" class="delivery_repository_plugin_class_name" [module="module_containing_the_delivery_repository_plugin_class"] [default="true|false"] [webservice="true|false"] [mode="direct|poll"] [pollInt="10000"] [enableMemoryCache="true|false"] [cacheFolder="folderPath"]>
			<parameter name="" value="" />
			<...>
		</deliveryRepository>
		<...>
	</repositories>	
	<...>
</parameters>

If you want to define multiple repositories, they should all be defined under the same <repositories></repositories> container.

Following common attributes are available on a Delivery Repository.

modes

1. direct: The Runtime will take into account new / updated deliveries at startup and when doing a publish operation from the various clients (Designer / Analytics / ...). Deliveries manually added or updated will be taken into account only at restart.
2. poll: The Runtime will check periodically if new deliveries are available in the repository. This is useful mostly for deliveries exposed as web service. To define the polling interval, please see the pollInt attribute.

parameters

Above attributes are common to all repository plugins.

Each repository plugin has also its own set of parameters which are defined under the repository container.

Those parameters are described in each dedicated plugin section.

Available Delivery Repository plugins

Below is the list of Delivery Repository plugins available on a default installation.

Note that additional plugins can be implemented to store deliveries in other locations.
You can contact us if you have specific requirements.

Repository Plugin – File Repository

File Repository Plugin is used to store deliveries locally in file system.

The plugin class to use is: «com.stambia.repository.delivery.FileDeliveryRepositoryPlugin».

The following parameters are available:

Example of repositories:

<repositories>
	<deliveryRepository name="default" class="com.stambia.repository.delivery.FileDeliveryRepositoryPlugin" default="true">
		<parameter name="folder" value="build/deliveries/"/>
	</deliveryRepository>		
	<deliveryRepository name="webservices" class="com.stambia.repository.delivery.FileDeliveryRepositoryPlugin" default="true" webservice="true">
		<parameter name="folder" value="build/deliveries/webservices/"/>
	</deliveryRepository>
</repositories>

Repository Plugin – HTTP Repository V1 – Analytics 2.x.x

HTTP Repository V1 Plugin allow to pull deliveries from a remote repository managed in Stambia Production Analytics 2.x.x.

This repository is used to perform delivery pulling, which means that the deliveries are pulled from a remote repository and not stored locally on the Runtime.

The plugin class to use is: «com.stambia.repository.delivery.HttpDeliveryRepositoryV1Plugin».

The following parameters are available:

This repository plugin requires that the name of the repository matches the name of a Deployment Manager defined in Stambia Production Analytics 2.x.x

Example of repository:

<repositories>
	<deliveryRepository name="analytics_2_deployment_manager_name" class="com.stambia.repository.delivery.HttpDeliveryRepositoryV1Plugin" default="false">
		<parameter name="url" value="http://localhost:8080/analytics"/>
		<parameter name="user" value="stambia"/>
		<parameter name="uncryptedPassword" value="stambia"/>
		<parameter name="unreachableTolerancePeriod" value="30000"/>
	</deliveryRepository>			
</repositories>

Repository Plugin – HTTP Repository V2 – Analytics 3.x.x

HTTP Repository V2 Plugin allow to pull deliveries from a remote repository managed in Stambia Production Analytics 3.x.x.

This repository is used to perform delivery pulling, which means that the deliveries are pulled from a remote repository and not stored locally on the Runtime.

The plugin class to use is: «com.stambia.repository.delivery.HttpDeliveryRepositoryV2Plugin».

The following parameters are available:

Deliveries executed from this repository are executed using the following path: <Analytics Project Name>/<Analytics Package Manager Name>/<Delivery name>.
For example: startdelivery.bat -repository analytics_3 -name ProjectA/ManagerA/DeliveryA
Refer to the «defaultDeliveryPath» parameter if you want the starting path to be defined automatically instead of having to define it in the execution command.

Example of repository:

<repositories>
	<deliveryRepository name="analytics_3_label_for_this_repository" class="com.stambia.repository.delivery.HttpDeliveryRepositoryV2Plugin" default="false">
		<parameter name="url" value="http://localhost:8080/analytics"/>
		<parameter name="user" value="stambia"/>
		<parameter name="uncryptedPassword" value="stambia"/>
		<parameter name="unreachableTolerancePeriod" value="30000"/>
		<parameter name="environment" value="analytics_environment_name"/>
		[<parameter name="defaultDeliveryPath" value="analytics_project_name/package_manager_name"/>]
	</deliveryRepository>
</repositories>

Legacy Delivery Repository configuration

Note that the legacy Delivery repository configuration is currently still supported for compatibility purposes.

If you have legacy repositories configuration you can use them in the Runtime, they will work.

However, we suggest using the new repository configuration presented above in this document when possible, it is the recommended way to configure the repositories.

Example of legacy configuration:

<repositories>
	<fileRepository name="default" default="true" folder="build/deliveries/"/> 
	<fileRepository name="webservices" default="true" folder="build/deliveries/webservices/" webService="true" synchPollingInterval="10000" scanMode="polling"/>
	<httpRepository name="analytics_2_deployment_manager_name" default="false" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" unreachableTolerancePeriod="30000"/>
	<httpRepository name="analytics_3_label_for_this_webservice_repository" environment="analytics_3_environment_name_to_retrieve_deliveries_from" default="true" url="http://localhost:8080/analytics" user="stambia" uncryptedPassword="stambia" unreachableTolerancePeriod="30000" webService="true" synchPollingInterval="10000" scanMode="polling"/>
</repositories>

Defining Jython scripting version

Jython is a language which can be used in scripting actions, allowing to use Python scripts in Java.

On a default installation Jython 2.2 version is shipped and used.

You can change the Jython version used by the Runtime through the following parameter:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="jythonVersion" value="2.2"/>
		<...>
	</engineParameters>
	<...>
</parameters>

If you want to use another version, create a folder under the following location in the Runtime and put inside the corresponding Jython libraries.

The name of the folder you choose will be the name of the version to specify in this parameter.

<Runtime Installation Folder>/lib/jython/<jythonVersion>

You can find Jython libraries in the official Jython website: https://www.jython.org/download
You must download the «Jython Standalone» library and put it in the folder you created in the Runtime.
For instance, if you created a folder named «2.7.1» inside the Runtime, copy / paste inside the Jython Standalone library you want to use and then specify «2.7.1» in the «jythonVersion» Runtime parameter, so that the Runtime will use the Jython contained in this folder for scripting actions.

Read carefully the Java prerequisites when you want to use other Jython versions to be sure it is compatible with the Java version you are using for your Runtime.

Defining Java Additional Options

Java options are generally added to the Java command launching the Runtime with the -DmyOption01=value01 argument.
This part allows to set them directly in the Runtime’s Configuration file through the javaConfiguration node.
The options specified inside will be loaded just after the Runtime’s start.

1. Open the engineParameters.xml file
2. Set the additional options you want to add at Runtime’s startup.

The syntax is the following:

<parameters>
	<...>
	<javaConfiguration>
		<property name="myOption01" value="value01"/>
		<property name="myOption02" value="value02"/>
		<...>
	</javaConfiguration>
	<...>
</parameters>

Securing the Runtime

A Runtime installed with the default configuration can be accessed by anyone.

Any user can connect and make operations on it, such as listing or executing sessions.

This behavior can be configured easily in the Runtime configuration file (engineParmeters.xml), that offer the possibility to secure the connection through

• RMIS (TLS secured RMI)
• HTTPS (TLS secured HTTP)
• Web Services TLS (HTTPS for published web services)
• User / Password with roles (permissions)
• Hostname / IP restriction

A basic security configuration looks like this:

For securing RMI, HTTP, and Web Services endpoints through TLS:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiEnableTls" value="true"/>
		<...>	
		<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>
		<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
		<parameter name="webServiceKeyStoreType" value="JKS"/> 
		<parameter name="webServiceKeyStorePassword" value="keystore_password"/> 
		<parameter name="webServiceKeyAlias" value="key_alias"/>
		<parameter name="webServiceKeyPassword" value="key_password"/>
		<...>
	</engineParameters>
	<...>
</parameters>

For user / hostname restriction:

<parameters>
	<...> 
	<security>
		<user anonymous="true" roles="Connect View"/>
		<user name="admin"  uncryptedPassword="admin" roles="Admin"/>
		<user name="developer"  uncryptedPassword="developer" roles="Connect View Execute"/>
		<user name="consult"  uncryptedPassword="consult" roles="Connect View"/>
		<allow address="192.168.0.42"/>
	</security>
	<...>
</parameters>

Warning: The security node must contain at least one user, which can be a normal or anonymous user.

Securing RMI, HTTP, and published web services with TLS

If you want to enable TLS for RMI, HTTP, and Web services endpoints, you have to define the following parameters:

<parameters>
	<...>
	<engineParameters>
		<...>
		<parameter name="rmiEnableTls" value="true"/>
		<...>	
		<parameter name="webServiceSecureProtocol" value="TLSv1.1"/>
		<parameter name="webServiceKeyStoreFile" value="D:/keystore/mykeystore.jks"/>
		<parameter name="webServiceKeyStoreType" value="JKS"/> 
		<parameter name="webServiceKeyStorePassword" value="keystore_password"/> 
		<parameter name="webServiceKeyAlias" value="key_alias"/>
		<parameter name="webServiceKeyPassword" value="key_password"/>
		<...>
	</engineParameters>
	<...>
</parameters>

Note that defining the keystore and certificate details is mandatory if you want to enable TLS.
They are used to secure all the different protocols: RMI, HTTP, and Web Services endpoints.
Once they are defined, they automatically secure RMI (if RMIS is enabled), HTTP and web services.

The following parameters are available

note about the clients

Note that once your Runtime endpoints are secure with TLS, the clients, such as the Designer, Analytics, or command line scripts, will need to know the certificate to be used for the communication.

If you are using certificates provided from an official authority, this will most of the time work without having to configure the certificate on the clients.

If you are using self-signed certificates, you will have to configure the clients to know this certificate.

Refer to this article to learn how to configure the various clients:
Communicating with Runtime

User / Password Restriction and Roles

You can define the users that can connect to the Runtime and their permissions.

The syntax is the following:

<parameters>
	<...> 
	<security>
		<...>
		<user anonymous="true" roles="Connect View"/>
		<user name="user01"  password="encrypted password" uncryptedPassword="plain text password" roles="Connect View Execute"/>
		<user name="user02"  password="encrypted password" uncryptedPassword="plain text password" roles="Connect View Execute"/>
		<...>
	</security>
	<...>
</parameters>

The following parameters are available:

The following roles are available:

About the Anonymous User:

An anonymous user can be set, to specify the permissions of the users that connect to the Runtime without specifying credentials.

<user anonymous="true" roles="Connect View"/>

When the anonymous user is set, it is therefore not mandatory to specify credentials when connecting.
The connected user will have the permissions of the anonymous user.

When the anonymous user is not set, specifying credentials when connecting is mandatory.
Anonymous connections will then be rejected.

Note that only one anonymous user can be set at a time.

Notes:
* Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).
* Only one of the password or uncryptedPassword should be set
* Multiple roles can be assigned to one user, separated with space characters

Warning: The security node must contain at least one user, which can be a normal or anonymous user.

Hostname / IP restriction

You can define the hostnames / IP addresses that are allowed to connect to the runtime.

The syntax is the following:

<parameters>
	<...> 
	<security>
		<...>
		<allow address="Hostname or IP Address"/>
		<allow address="Another Hostname or another IP Address"/>
		<...>
	</security>
	<...>
</parameters>

Warning: The security node must also contain at least one user, which can be a normal or anonymous user.

Scheduler configuration

Configuring internal scheduler

The scheduler shipped with the Runtime stores all the schedules into a database.
This database is by default an internal H2 database, that is shipped with the Runtime and started with it.

If you want to change this and store the schedules into another database:

• Create the necessary tables in the target database using the scripts that are in stambiaRuntime/scripts/scheduler
• Copy the stambiaRuntime/properties/samples/schedules/engineScheduler.properties into stambiaRuntime/properties
• Open it and configure it as explained below

When the property org.quartz.jobStore.dataSource is set to internal (which is the default), the scheduler stores its schedules in the internal database.
Therefore, change it to another name when you want to use another database.

Finally, define the datasource parameters to match the location where the tables are created.

org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreTX
org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.StdJDBCDelegate 
org.quartz.jobStore.useProperties=false
#org.quartz.jobStore.dataSource=internal
org.quartz.jobStore.dataSource=database01
org.quartz.jobStore.tablePrefix=STB_
org.quartz.jobStore.isClustered=false
#============================================================================
# Configure Datasources  
#============================================================================
org.quartz.dataSource.database01.driver =org.h2.Driver
org.quartz.dataSource.database01.URL = jdbc:h2:tcp://localhost:42100/scheduler/internalDb;SCHEMA=SCHEDULER
org.quartz.dataSource.database01.user = sa
org.quartz.dataSource.database01.password = 
org.quartz.dataSource.database01.maxConnections = 5
org.quartz.dataSource.database01.validationQuery=
org.quartz.dataSource.database01.module=internal

Warning: For the Runtime scheduler to be able to communicate with the database, you must install the corresponding JDBC driver inside Runtime’s ‹default› Module. For instance, if you want to use Oracle as scheduler database, install Oracle’s JDBC driver in Runtime’s ‹default› Module.

Log database automatic purge

Purging automatically log database

You can plan an automatic purge of the Runtime session logs.
This can be done in Stambia and Stambia Analytics in the Purge tab of the Runtime Editor or alternatively on command line as explained below.

To proceed:

1. Launch startCommand (.bat or .sh).
2. Then use the purge scheduling command, the description of which follows:

schedule purge keep <number> <minute|hour|day|session>  cron <cronExpression> [sessionname <name,name2,...>] [status <done,error,killed>] [on host <hostname>] [port <hostport>]

It is possible to purge while keeping:

• A number of days, hours or minutes
• A number of sessions

For example, to keep 90 days and schedule the purge every evening at 23h:

schedule purge keep 90 day cron "0 0 23 * * ?"

Modules location configuration

Changing default Modules location

When starting, the Runtime will load all the Modules located in the modules folder which is in Runtime installation folder.

You can change the location of this folder to another location by updating the initvariables.bat (Windows) or initavariables.sh (Linux / MAC) script which is in the Runtime installation folder.

Open this file and update the following variable with your desired location:

STAMBIA_MODULES_PATH=modules

Default value is a relative path to the ‹modules› folder inside the Runtime.

You can use absolute path also.

Refer to Developer’s Guide for further information about Modules.

If you are changing the Runtime’s Modules location, all the Modules will be loaded from this folder at Runtime’s startup. So if you are changing this on the Runtime which is included in the Designer, make sure this is consistent with the location where the Designer will manage the Modules. Moreover, as the Designer is reinitializing the included Runtime’s files at startup, make sure also to include the initvariables.bat / initvariables.sh script to the properties/protection.rules file to avoid your modification to be erased at Designer startup.

Runtime parameters reference

The configuration of the Runtime is done in the engineParameters.xml file that can be found in the properties folder of the Runtime’s installation.
This file allows to manage:

• The engine parameters (such as started services, listening ports, ...)
• The security of the Runtime (hostname and user / password restriction, roles)
• The repositories where the deliveries are stored
• The Java additional options to add at Runtime’s startup
• The log database configuration

Take care, it is highly recommended to check first with Stambia the modifications you wish to bring to the XML files containing the Runtime parameters.
You can moreover find configuration samples in the properties/samples folder.

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Tip: All the parameters are centralized in this file but can be easily externalized if required.

Engine Parameters

Common Parameters

Services Parameters

Services Ports Parameters

Services Security

Services Miscellaneous Parameters

Standard Output Parameters

Web Services Parameters

Logs parameters

In this part, the default values will be those used for the logs in H2 (the internal base). For other logs examples, please refer to the example files that are provided.

Log header

synchMode

1. synch : session logs are synchronous, while being executing, a session will log synchronously all its session logs. This is the default mode used.
2. asynch : while being executing, a session will log asynchronously all its session logs, the session will continue to be executed without waiting for the information to be logged in database.
3. synchFirstLog : this mode is therefore a mix between the synch and asynch mode. The first log of the session will be synchronous, to be sure that at least one log has worked and that the log database is available, then the following logs will all be asynchronous.

Internal parameters

Note: Passwords are encrypted using the encrypt <password> command on the Runtime engine console (engine command line tool).

Session Log Level

The session log level defines the level of information which is logged inside log database for each session executed by the Runtime.

The higher the value is the higher information are logged.
You can find below the different log level values and what level of details can be consulted, depending on the session status.

Runtime upgrade

Overview

Upgrade procedure is described below.

Depending on if you are upgrading between minor versions, or if you are upgrading to a new major version, the procedure may change, please read carefully the procedure details below.

Major version upgrade procedure

If you are upgrading from Stambia S17.x.x to Stambia 2020 (S20.x.x), please refer to complete upgrade / migration procedure:

https://stambia.org/doc/53-stambia-di-software/runtime/installation-and-upgrade/69-upgrading-a-runtime-instance

Minor version upgrade procedure

If you are upgrading from S20.0.x to another S20.0.x version you can follow the procedure below.

After downloading the desired Runtime ZIP archive, proceed through the steps listed below.

We assume your current Runtime is installed into a directory named «stambiaRuntime».

1. Install the new Runtime in a new directory, something like "stambiaRuntime_new"
2. On UNIX/Linux systems make sure that all the stambiaRuntime_new/*.sh files are executable
3. Stop the old Runtime and make a backup
4. Copy the content of the following directories from the old Runtime to the new Runtime:
   1. stambiaRuntime\build\deliveries
   2. stambiaRuntime\build\packages
   3. stambiaRuntime\modules
   4. stambiaRuntime\properties (if you have set some properties)
   5. stambiaRuntime\scheduler (if you are using the Runtime’s scheduler)
   6. stambiaRuntime\sessions (if you use the Runtime’s internal log database)
   7. Optionally: stambiaRuntime\temp (if your Processes store specific files intentionnally in this directory)
5. Rename the old Runtime’s directory to something like "stambiaRuntime_old"
6. Rename the new Runtime’s directory to "stambiaRuntime"
7. Apply the read / right permissions to the new folder as it was set on the old one
8. If the Runtime is installed as a Windows service, remove and re-install the service
9. Start the Runtime

Troubleshooting

You will find in this section some tips and help for troubleshooting common issues.

MAC OS – Runtime startup and execution time is slow

You installed a Runtime on MAC OS, and you notice that Runtime’s startup is very slow, as well as executing sessions.

Refer to the following article which will guide you to try resolving this issue.

Runtime startup and execution time is slow on MAC OS