Setup and Installation

Engine has three required components: a database to store Engine application data, a filesystem to store courses, and an application server to serve these courses. Detailed instruction on configuring these components follows.

Please see the System Requirements page for details on the platforms and software versions we support with Engine 2018.1.

Database Setup

Database Connectors

For legal reasons, we are not generally allowed to redistribute the database connectors for most platforms, so you may need to download them before continuing.

On .NET, we are able to include the connectors for SQL Server and PostgreSQL. If you are running .NET with MySql or Oracle, you must download the official .NET connector from your database's vendor. (MySQL .NET connector or Oracle .NET connector). Once you have downloaded the driver dll, place it in the RusticiEngine\bin folder of your Engine distribution.

If you are running Java, you need to download a JDBC connector.

Once you've downloaded the appropriate driver, place it in the Installer/lib folder of your Engine distribution so it will be available for the installer.

Preliminary Considerations

As discussed in the overview of Engine, Engine supports the concept of segmenting data for multiple tenants. As part of this, we support storing data for all tenants in a single database, or separating out each tenant into its own database (or a hybrid approach with clusters of tenants in separate databases).

By default, Engine assumes that you are using a single database for all tenants. This is the simplest and most straightforward way to run Engine. If you feel like you may want to have separate tenant databases, please see the Advanced Database Setup section for more information.

Before you use the installation tool, you will need to create any new databases, users, or tablespaces required for your setup, as the installer expects the database to exist already.

Installation Tool

Before you can actually run the install tool, if you are using MySQL or Oracle, you will need to copy the database connectors required by your installation into RusticiEngine/binInstaller/lib.

Once you've done that, you just need to open the RusticiEngine/binInstaller folder of your Engine distribution in your command line and execute the install tool.

For the majority of Engine implementations, the command you need to run the install tool is just:

EngineInstall.exe <persistenceEngine> <connectionString> [schemaPrefix]

java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp <persistenceEngine> <connectionString> [schemaPrefix]

  • <persistenceEngine> is the name of your DBMS. The value should be either sqlserver, mysql, oracle, or postgresql.
  • <connectionString> is the quoted connection string for the database that you want to install Engine on, followed by a pipe (|) and the class name of your JDBC connector. Make sure that the user specified in your connection string has the appropriate permissions to create and alter any of the necessary tables in Engine's schema.
  • [schemaPrefix] is the name of the schema that Engine's tables should be created in. This value is optional. If not included, Engine will use the default schema for the user provided in the connection string.

Here's an example of a typical installation command (without the schemaPrefix specified):

EngineInstall.exe sqlserver "Server=ServerName;Database=Engine;User Id=user;Password=password;"

java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp mysql "jdbc:mysql://myHostName/myDbName?user=myUserName&password=mypassword|com.mysql.jdbc.Driver"

This command can vary depending on the particular architecture of your Engine integration. The default instructions above apply to customers who have a single database for their Engine installation.

For installing tenants in separate databases, see the details in the Advanced Database Setup section.

Application Server Setup

Every customer application environment into which Engine is deployed is a snowflake. We don't pretend to be server configuration experts for every possible scenario, as our primary goal is to ensure that Engine can run comfortably according to your administrative preferences and expertise. That said, we can typically ensure that Engine can be stood up in a given supported environment.

Engine for .NET runs as a web application and requires .NET Framework 4.5. You can drop the entire RusticiEngine folder onto your application server and create an IIS application that points to it.

You might want to map a virtual directory to your content folder for use with Engine, depending on how you intend to store and serve content.

Engine for Java needs a Java application container to run and requires Java 8+. SCORM Cloud, our hosted training delivery system, runs on Tomcat, and most of our development team uses Tomcat for testing. Because of this, we'll cover the basics of setting up Engine for Tomcat in this document. We generally support Engine's use with other Java application containers, though, but configuring Engine for use with all Java application containers is outside the scope of this document.

We ship Engine as a WAR file, which can be dropped in Tomcat's webapps directory. Your RusticiEngineSettings.properties file should be put in a folder that is in the web application's classpath (like Tomcat's /lib folder).

We also ship Engine with a context.xml template that you can use as a reference for configuring a JNDI resource for your database connection string.

We specifically recommend that you do not use your Java application container to serve content through Engine. Instead, you should look at hosting with a traditional web server. There are a variety of ways to map your web server so that the web paths referenced by Engine are served by a web server rather than the app server serving Engine.

Required Configuration

Engine is a highly configurable application. Our goal is that Engine fits seamlessly into your ecosystem. These are the settings that are required for almost every installation of Engine, but we will also continue to reference other settings and their effects through most of our documentation.

While most of these settings have default values that will work for many of our customers, there are a few that must be configured before certain functionality of Engine can be utilized. Engine can be configured using a couple of different approaches, but the most common and most basic is through your Engine config file.

Engine ships with an XML file called RusticiEngineSettings.config for the .NET platformRusticiEngineSettings.properties for our Java platform.

To add a setting, just insert a setting entry anywhere in the root element using the format of <add key="SettingName" value="SettingValue"/><entry key="SettingName">SettingValue</entry>.

After adding or changing a setting to your config file, you should restart the Engine web application to make sure that the change is picked up.

  • DataPersistenceEngine configures which DBMS you are using to store Engine's data. The acceptable values for this setting are sqlserver, mysql, oracle, and postgresql.
  • DatabaseConnectionString is the connection string Engine will use to communicate with its database. This may be a full connection string or a JNDI resource name. If you want to use multiple databases to store Engine's data, please refer here for a detailed explanation of your options. }
  • RusticiEngineUrl: You should change the value of this setting to match the URL that Engine is being hosted on. You can either specify the entire URL (i.e. https://example.com/RusticiEngine), or you can just specify the directory that Engine is on (/RusticiEngine).
  • ApiBasicAccounts: To integrate with Engine's REST API, you will need to configure the accounts that are authorized to use it. The value for this setting should be a newline-delimited list of username/password pairs in the format of username:password. The account credentials would be used for Basic Auth to Engine. You'll need at least one account here to get started. For more information about the role that these API accounts play in your application, please refer to the security section of our docs.
  • RedirectOnExitUrl: used to specify where Engine should deliver your learners upon exiting their course. By default, it will direct to a placeholder page that ships with Engine, but you will likely want to replace that value with some sort of dashboard or landing page within your own application. Like many settings, this can also be configured on a per-tenant, or even per-launch basis if a global value is not desirable.
  • SystemHomepageUrl: This setting is required if you want to support the use of xAPI courses. It is used in creating certain identifiers in xAPI. The value you specify should be permanent, as changing it can impact data retrieval in xAPI. You can read more about how to pick a value for SystemHomepageUrl here;

Load Balancer Configuration

For various operations, Engine will need to construct a fully qualified URL by referencing the incoming request. If you're running Engine behind a load balancer or a reverse proxy, there are certain issues that can arise if not configured properly. Many times in environments like this, the request from the load balancer to Engine will use an internal domain or an insecure protocol like HTTP. Engine, not knowing that the request came from a load balancer, will construct a fully qualified URL using this domain and protocol. The resulting URL may be unusable because of the internal domain or the insecure protocol.

To combat this scenario, you should configure your load balancer to pass the original host and protocol of the request via HTTP headers. Engine will look for and use a couple different headers when constructing a URL, in the following order:

  1. The "Forwarded" HTTP header for RFC7239-style reverse proxying. If it's present, Engine will check the "host" and "proto" segments in the value of that header to determine the original host and protocol.
  2. Engine then checks for either the "x-forwarded-proto" or "x-forwarded-host" HTTP headers (which were the industry standard way to solve this problem before RFC7239 adoption). If either header is present, it will use the given host and protocol for the original URL.
  3. Last, Engine checks for the IIS/ARR-specific header "x-arr-ssl", and will set the request to be https if it is found.

You can read more about this in one of our articles that you can find here: https://support.scorm.com/hc/en-us/articles/360000388554-Using-Engine-Behind-a-Proxy-or-Load-Balancer

Logging

Logging is handled exclusively through log4net, an open-source logging library bundled with Engine. A sensible default configuration for log4net is provided in our web.config templates, but this configuration can be edited or replaced at will. If the configuration is missing, Engine will still run, but nothing will be logged.

The default log4net configuration included in our web.config templates will log only those messages with a log level of WARN or higher. These messages will be written to a rolling log file under C:\logs\rusticiengine-log.txt. They will also be written to the ASP.NET trace, with categories corresponding to their log level.

Most logging is handled primarily through SLF4J, an open-source interface to several other logging libraries.

SLF4J can be used in combination with many other logging frameworks. In order to enable a particular framework, you must download the appropriate SLF4J adapter from the SLF4J project website and place it in the classpath for your web application. Engine already ships with logback, an open-source logging library, and its SLF4J adapter so that logging will work "right out of the box."

We also ship with a default logback configuration file, which is deployed when the WAR is deployed. The file, logback.xml, is located in the WEB-INF/classes directory of your deployed application.

That said, we do not recommend you edit this configuration, lest your changes get overwritten when you re-deploy Engine after a maintenance release. Instead, we recommend you take advantage of the fact that logback.xml is logback's last choice for a configuration file. If you place a logback.groovy or logback-test.xml file in your web application classpath, logback will load that configuration instead. For more information on logback's configuration file format, see the tutorial on the logback project website.

Note: for performance reasons, we do not recommend running with DEBUG level logging enabled in your production environments. The heavy amount of logging involved can degrade performance in some logging configurations, especially on .NET.

Advanced Database Setup

Clearly, keeping all Engine's data together in the same place is the simplest way to set up Engine, and we strongly recommend it. However, for technical reasons, some customers may want to use multiple databases to support tenancy. The details below are for setting up Engine for this scenario.

Separate System and Tenant Databases

Engine requires the use of two database schemas. By default, Engine will install both of these schemas into the single database you specify to the intaller. To have them installed into separate databases, you'll need to follow the instructions below.

First, there is the system schema, which contains information that is shared between all of Engine's tenants. This includes the catalog of tenants themselves, as well as some tables related to configuration settings. There can never be more than one system schema (nor should there need to be). The connection string for system tables is governed by the SystemDatabaseConnectionString configuration setting.

To install only the system schema, you add a -system flag to the the installer instructions specified above:

EngineInstall.exe <persistenceEngine> <systemDatabaseConnectionString> -system

java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp <persistenceEngine> <systemDatabaseConnectionString> -system

Second, there is the tenant schema, which contains all tenanted information. If your application needs to use different databases for each tenant, this is the schema that needs to be duplicated. The connection string for these tables is governed by the TenantDatabaseConnectionString configuration setting.

To install only the tenant schema, you will need to run the installer with some additional parameters:

EngineInstall.exe <persistenceEngine> <systemDatabaseConnectionString> <tenantDatabaseConnectionString> [schemaPrefix] <tenantName> -tenant

java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp <persistenceEngine> <systemDatabaseConnectionString> <tenantDatabaseConnectionString> [schemaPrefix] <tenantName> -tenant

  • persistenceEngine and schemaPrefix are described above.
  • systemDatabaseConnectionString is the connection string for your system database.
  • tenantDatabaseConnectionString is the connection string for the new tenant database.
  • tenantName is the name of the tenant for this database. It should be unique, and is required.

Configure Engine for Multiple Tenant Databases

When you store each tenant's data in separate databases, you have to let Engine know where to find that data for a particular tenant. To do this, you need to configure the TenantDatabaseConnectionString for each of your tenants. Engine provides a couple of different ways of doing that.

Tenant Setting Prefix

If you just have a few rarely-changing tenants, it might be easiest to configure the connection strings for each tenant individually in Engine's config file. Engine provides a special format for configuration settings in which the setting name is prefixed with the name of the tenant that the setting value is scoped to.

For example, if you had a tenant whose name was "tenant123", then you could just add a setting to your Engine config file with the name "tenant123.TenantDatabaseConnectionString" and a value of the connection string pointing to tenant123's database.

<add key="tenant123.TenantDatabaseConnectionString" value="Server=ServerName;Database=Engine-tenant123;User Id=user;Password=password;" />

<entry key="tenant123.TenantDatabaseConnectionString">jdbc:mysql://myHostName/myDbName?user=myUserName&amp;password=mypassword|com.mysql.jdbc.Driver</entry>

Tenant Replacement Token

If your cast of tenants is large, or changing fairly quickly, then maybe a static file isn't the best approach for your team. For this, Engine does allow for the ability to dynamically generate a setting value based on the scope in which it is being loaded. You can do this through the use of tokens that Engine looks for an replaces as it loads a setting.

For example, if you wanted every Engine tenant to have their own database named after themselves in the format of Engine-[Tenant Name], then you could set the value of TenantDatabaseConnectionString in your Engine config file to something like the following:

<add key="TenantDatabaseConnectionString" value="Server=ServerName;Database=Engine-${TenantName};User Id=user;Password=password;" />

<entry key="TenantDatabaseConnectionString">jdbc:mysql://myHostName/Engine-${TenantName}?user=myUserName&amp;password=mypassword|com.mysql.jdbc.Driver</entry>

Tenant Configuration API

If you would rather wait until your team has confirmed that a tenant's database already exists before trying to use it, or the desired names for your database can't be generated based solely from tenant's name, then you can configure this settings through the API.

Once you've confirmed that the database for your tenant is in place, all you would need to do is set the value for TenantDatabaseConnectionString to the appropriate connection string using the API. You can refer to our docs on configuration through the API to learn about the implementation details of this strategy.

Running Without a System Database

It is possible to run Engine without a system database, but its operation does come with restrictions. If you think you need to utilize this functionality, please reach out to Rustici support staff for more details.

results matching ""

    No results matching ""