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 2017.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 ScormEngineInterface\bin
folder of your Engine distribution.
If you are running Java, you need to download a JDBC connector.
- For SQL Server, we recommend the official Microsoft SqlServer JDBC driver, although some customers have reported success using the JTDS driver.
- For Oracle, download the appropriate driver for your Oracle version and Java version directly from the Oracle website
- For MySQL, you will need to download MySQL Connector/J.
- For PostgreSQL, download the appropriate driver for your Java version directly from the PostgreSQL website.
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 ScormEngineInterface/bin
Installer/lib
.
Once you've done that, you just need to open the ScormEngineInterface/bin
Installer
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 eithersqlserver
,mysql
,oracle
, orpostgresql
.<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=ScormEngine;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 ScormEngineInterface
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 7+, though for security reasons we strongly recommend Java 8 or above. 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 SCORMEngineSettings.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 SCORMEngineSettings.config
for the .NET platformSCORMEngineSettings.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 aresqlserver
,mysql
,oracle
, andpostgresql
.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. }ScormEngineUrl
: 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/ScormEngineInterface
), or you can just specify the directory that Engine is on (/ScormEngineInterface
).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 ofusername:password
. The account credentials would be used for Basic Auth to Engine. 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;
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\scormengine-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
andschemaPrefix
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=ScormEngine-tenant123;User Id=user;Password=password;" />
<entry key="tenant123.TenantDatabaseConnectionString">jdbc:mysql://myHostName/myDbName?user=myUserName&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&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.