On-Premises Installation¶

About Modelshop¶

Modelshop is a data analytic platform that enables customers to easily create mission critical applications that ingest large, complex data sets and execute pre-defined rules. It can be used to analyze trade reports or financial portfolios, evaluate predictive models, perform simulations and make real-time decisions.

Customers have also used the platform to transform ad-hoc, error prone, manual intensive spreadsheets into analytics that are automated, secure, auditable, cloud accessible and significantly reduce analysis cycle time.

Modelshop Installation¶

This guide describes the process for installing Modelshop . The product relies on Java and Tomcat services and connects to external data sources such as relational databases and file stores. Since it is a pure Java platform, it can be installed on a Linux operating system (preferred) or on a Windows server.

Modelshop also provides a stand-alone distribution where a full installation can be deployed as a single TAR file (not including Java).

Modelshop optionally integrates with the H2O.ai machine learning platform, as well as the Python platform running as a Flask server through a Modelshop Python plugin.

This document scope addresses the installation of the core product and does not address setup and configuration of external data sources or the H2O, Python environments.

Native installation of Modelshop should require between 1 to 2 hours, depending on environment complexity. Install time can be reduced to around 30 minutes by using the stand-alone distribution.

Hardware and Network Requirements¶

The hardware sizing estimates for Modelshop will vary based on the solution business requirements.

Modelshop’s models are executed in memory, so selecting hardware that can handle large RAM sizes in a cost-effective manner are the best choice. The table below provides a guide for estimating the environment needed for Modelshop based on typical processing demands; it will vary based on the complexity of data, complexity of business logic and required processing constraints such as compute execution window (for batch) and response latency (for real-time).

Configuration	Typical Workload	Server Configuration
Small	2-3 Concurrent Models 100’s of Thousands of Records	4 CPU, 16G Mem
Medium	5-10 Concurrent Models Millions of Records	8 CPU, 32G Mem
Large	10-20 Concurrent Models 10’s of Millions of Records	16 CPU, 64G Mem
X Large	20-30 Concurrent Models 100M Records	32 CPU, 128G Mem
XX Large	30-50 Concurrent Models 500M Records	64 CPU, 512G Mem

These configurations are based on ‘near real-time’ performance, where the bulk of data and calculations are available in memory (after data load) for top performance. For larger processing jobs it is possible to use a smaller configuration and segment the job into batches that run over time. For example, a ‘Large’ configuration may be suitable for processing 100s of millions of records if the processing window for calculating the model could take an hour instead of minutes.

Additionally, 500GB Disk – for model storage, application and OS

Backup and data landing storage – based on solution business requirements

Preparing the Modelshop Installation Location¶

Modelshop can be installed at various locations on your server. It is recommended that you create a new disk mount specifically for Modelshop. By convention, the Modelshop volume would typically be mounted at /modelshop and this mount clusterPoint is used to facilitate permanent volume restoration and backups. The rest of this installation guide will assume the /modelshop root install location.

Install OpenJDK (or alternative)¶

Note: JDK11 is currently recommended to ensure compatibility with many big-data open source projects such as Hadoop. Modelshop is also fully tested, and runs more efficiently on Java11. If you have no need to integrate with open-source data projects you can consider installing Java11 instead. Alternative Java versions based on the same spec such as Oracle’s Java can be used. At this time AIX variants are not recommended due to severe performance constraints.

Install OpenJDK 11. The following example shows how this is done on Ubuntu with standard options.

Note: These install instructions assume Ubuntu syntax. If installing on RedHat, yum commands must be substituted for apt-get commands. (apt -> yum, add-apt-repository -> yum-config-manager –add-repo). Depending on licensing restrictions, alternate version of Java may be required.

On Ubuntu:

$ sudo add-apt-repository ppa:openjdk-r/ppa
$ sudo apt update
$ sudo apt install openjdk-11-jdk

Verify that the installation was successful and the right version of Java is selected with the following:

$ java --version
openjdk 11.0.11 2021-04-20
OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04)
OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode, sharing)

If the incorrect version of Java is displayed, please refer to documentation on the ‘update-alternatives’ command in linux to assign the correct version of Java as the default.

Stand Alone Quick Install¶

This section describes how to deploy Modelshop using the stand-alone quick installation image. With this approach, everything needed to get an instance of Modelshop up and running quickly is included in a combined .tar file and install scripts. This approach uses the default installation locations and settings and is recommended for most installations. It is possible to do the stand-alone quick install but then to leverage sections of the manual installation to customize settings as needed.

Note Prerequisites: At this clusterPoint you should have a linux server and a user with sudo access. Java 11 or later should be installed and confirmed with the ‘java –version’ command. There should be a volume mounted (or a directory that is part of a permanent, backed up volume) located at /modelshop.

From the /modelshop directory, download the stand-alone Modelshop distribution. The path to the latest distribution can be provided by the Modelshop team, or if you have access to cloud.modelshop.com you can find the correct distribution and copy the ‘public link’ address. Alternatively, the latest distribution can be downloaded directly from the cloud using a browser and then transferred to the server using SFTP or a similar technology.

/modelshop
$ sudo curl -k -o modelshop-standalone.tar.gz https://cloud.modelshop.com/index.php/s/xtuBcwOz66c179a/download
$ sudo gunzip modelshop-standalone.tar.gz
$ sudo tar -xvf modelshop-standalone.tar
$ ls
app  bin  etc  modelshop-python  modelshop-standalone.tar  standalone-readme.md  tomcat

To complete the stand-alone modelshop installation, run the install.sh script:

/modelshop
$ sudo ./bin/install.sh

To update to the very latest version of Modelshop runtime (this can be repeated for upgrading the software). The latest install link is shown below, however other links may be provided by Modelshop for patches or non-latest releases.

/modelshop
$ sudo ./bin/update.sh https://cloud.modelshop.com/index.php/s/7CVIZ5A2Q6ZVEGP/download

By default, Modelshop operates on non-privledged ports 8080 (http) and 8443 (https). If you plan to add an application gateway or other routing to the default ports 80 (http) and 443 (https) then skip this next step.

/modelshop
$ sudo ./bin/redirect_ports.sh

The Modelshop server can be started and stopped with the following commands (this can be run from any directory):

$ sudo service tomcat start
$ sudo service tomcat stop

You can test that the Modelshop server is running with the following command (note if you ran the stop command above you need to start it again):

If you are on a server not yet exposed to a browser, test access using the curl command (e.g.):

$ curl http://localhost:8080/modelshop/api/ping/ping

The response should be PONG.

Assuming the server has a DNS entry and it is configured to be accessible through HTTP port 80, you can access the Modelshop UI through a browser at the following address:

http://app.sample.com/modelshop

where ‘app.sample.com’ is the DNS path to the server address (or it can be replaced with an explicit IP address).

The default install login is admin/admin - please change it or replace this default user with another admin user(s). Additional users can be configured using the Administration area for the admin user.

Additional Setup¶

When using the stand-alone setup, there are a few sections of the manual setup that may need to be accomplished to customize the install. Review the following and make adjustments as needed:

Adjust Tomcat settings like memory or JVM

Adjust Modelshop properties like URL and domain name

Set up SSL if needed

Add white-labeling

Add OAuth2/OpenID Single Sign-On integration

Integrate with an eMail server

Other integrations like JDBC and H2O

Manual Modelshop Install¶

This section walks through a step-by-step manual installation of Modelshop, including manual installation and setup of Tomcat and creation of Modelshop configuration parameters. It is recommended that the stand-alone installation be used when possible, and that this manual section be referenced for any required customizations, or to better understand the deployment architecture.

Access to Modelshop Distribution¶

Resources required to install Modelshop can be downloaded from Modelshop’s cloud file sharing platform at:

https://cloud.modelshop.com

The location of the latest release distributions can be found here: https://cloud.modelshop.com/index.php/apps/files/?dir=/Distribution

Currently, accessing Modelshop’s on-premise installation requires a cloud account, which can be provided by a Modelshop representative or a Modelshop partner.

To begin the installation process, the following files should be downloaded and placed on the installation target machine:

modelshop-standalone.tar.gz This has all of the seed file structures and includes a version of tomcat. You can choose to install tomcat independenly per the instructions below. modelshop.war The latest runtime image for Modelshop (last major release will already be included in the standalone tar above)

Install and Configure Tomcat¶

These Tomcat installations instructions are meant to be the minimum Tomcat install required to launch a Modelshop server. Steps that are unique to Modelshop will be highlighted so they can be applied to a custom Tomcat installation. Topics such as load balancing and SSL support are covered in standard Tomcat documentation and are not replicated here. Please refer to Apache’s Application Developer’s Guide for options on how to optimally configure Tomcat for your environment:

The examples will assume a standard Ubuntu installation. The first step is to create a tomcat user:

$ sudo groupadd tomcat
$ sudo useradd -s /bin/false -g tomcat -d /modelshop/tomcat tomcat

Manual Tomcat Installation¶

https://tomcat.apache.org/tomcat-9.0-doc/appdev/installation.html

Download the tar file to the /tmp directory:

$ cd /tmp
$ curl -O https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.16/bin/apache-tomcat-9.0.16.tar.gz

Tomcat may be installed in various locations depending on the operating system. We recommend installing it in the modelshop install directory, in our example /modelshop:

$ cd /modelshop
$ sudo tar xzvf /tmp/apache-tomcat-9.0.16.tar.gz
$ sudo mv apache-tomcat-9.0.16 tomcat

Setup Tomcat Permissions¶

$ sudo chgrp -R tomcat tomcat
$ cd tomcat
$ sudo chmod -R go+r conf webapps logs
$ sudo chmod go+x conf webapps logs
$ sudo chown -R tomcat webapps work temp logs

Create Tomcat Service¶

Create the tomcat service file, which will allow convenient starting and stopping of the Tomcat server:

$ cd /modelshop
$ sudo mkdir etc
$ cd etc
$ sudo mkdir systemd
$ cd systemd
$ sudo mkdir system
$ cd system
$ sudo vi tomcat.service

Add the following text to the file. Make sure the setting for JAVA_HOME is correct:

NOTE: adjust Xmx to be the desired memory allocation for Modelshop, suggested no more than 80% of machine RAM

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking

Environment=JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
Environment=CATALINA_PID=/modelshop/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/modelshop/tomcat
Environment=CATALINA_BASE=/modelshop/tomcat
ExecStart=/modelshop/tomcat/bin/startup.sh
ExecStop=/modelshop/tomcat/bin/shutdown.sh
Environment='JAVA_OPTS=-Djava.awt.headless=true -Xmx14G -XX:+UseConcMarkSweepGC'

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always
SuccessExitStatus=0 1

[Install]
WantedBy=multi-user.target

Save the file and exit the editor. Make a symbolic link to the file:

$ cd /etc/systemd/system
$ sudo ln -s /modelshop/etc/systemd/system/tomcat.service tomcat.s:ervice

Reload the systemd daemon:

$ sudo systemctl daemon-reload

NOTE: MODELSHOP SPECIFIC STEP

Add the following to the bottom of /modelshop/tomcat/conf/catalina.properties:

# allows paths to be sent as URL params through Jersey
org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

# Modelshop configuration -
spring.profiles.active=local

# set modelshop repo root
modelshop.repo.root=file:/modelshop/app

You may need to adjust the path on the last line, depending on where the modelshop repo is installed in the next section.

When complete, launch tomcat using the standard launch process, and ensure that tomcat is running:

$ sudo service tomcat start
$ sudo service tomcat status

With a default configuration, you can view the tomcat welcome page at your base URL. Your configuration may differ.

NOTE: It is recommended that a load balancer be installed in front of tomcat (Apache or similar) and be exposed on a standard HTTPS (443) port. The installation and configuration of a HTTPS load balancer is beyond the scope of this installation guide and will be dependent on the client’s specific environment.

Set up SSL for Tomcat¶

Note: These instructions for setting up an SSL cert for Tomcat are provided to help clients get a standard implementation of SSL installed and running quickly. If a custom setup is needed, please refer to Apache Tomcat documentation available online that describe SSL setup options: https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html

By default, Tomcat is set up to listen on port 8080 (HTTP, not HTTPS). The stand-alone server is also configured to listen on the default HTTP port, 80, via redirect (optional). If SSL is needed, the Tomcat server must be configured to listen on port 443 (HTTPS) and an SSL cert must be registered. A free self-sign cert can be utilized for internl SSL use or a third-party cert vendor (some are also free) can be utilized for added end-user confidence.

If a self-signed cert is required, one can be created with the following commands (assumes Ubuntu Linux). Skip this step if using a commercial or existing SSL cert:

/modelshop
% sudo mkdir ssl
% cd ssl
% sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout modelshop.key -out modelshop.crt

You will be required to answer multiple questions about the organization which will be signed into the cert. Once created the SSL cert files will be as follows (in the /modelshop/ssl dir)

modelshop.crt (The cert file, starts with a BEGIN CERTIFICATE heading)

modelshop.key (The private key, starts with a BEGIN PRIVATE KEY heading)

If you obtained ssl cert files externally, they may have different suffixes (e.g. the key file could end in .pem). Verify the files are correct by making sure they have the correct start and stop tags as shown above.

On Linux, these certs must assigned to the tomcat user

/modelshop/ssl
$ sudo chown -R tomcat:tomcat ../*

SSL is registered in the server.xml file - in our default setup that is located at /modelshop/tomcat/conf/server.xml

In the default server.xml, you will find a connector setup for HTTP on port 80 as well as a commented out section for HTTPS on port 443. If you want to support HTTPS you can leave the port 80 connector and uncomment the port 443 connector as shown below (customizing to clusterPoint to your own cert files if required). If you were unable to set Tomcat up on the restricted ports 80 and 443, alternate ports 8080 and 8443 can be used instead. If alternate ports are used, they will need to be appended to the URL after the base server name (e.g. https://localhost:8443/modelshop)

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
       maxThreads="150" SSLEnabled="true" >
       <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
       <SSLHostConfig>
               <Certificate certificateKeyFile="/modelshop/ssl/modelshop.key"
                       certificateFile="/modelshop/ssl/modelshop.crt"
                       type="RSA" />
       </SSLHostConfig>
</Connector>

To verify the server is listening on HTTPS port 8443 execute the following command (after restarting the server, which may take 15-20 seconds to start):

Upon restarting the Tomcat server, you may want to check the main Tomcat log file at /modelshop/tomcat/logs/catalina.out to ensure that the connector was initiated correctly.

$ sudo service tomcat restart
$ curl -k https://localhost:8443/modelshop/api/ping/ping

The response should be PONG. Note the addition of the -k option to ignore a self-signed cert warning.

The application UI should now be accessible via https. If you used a self-signed cert, you will have to bypass the ‘not secure’ warning of the browser.

https://app.sample.com:8443/modelshop

Configuring directly to ports 80, 443¶

If it is preferred to configure Tomcat directly on ports 80 and 443 (rather than the port redirect), the authbind utility can be used. To enable authbind, install it and run the following script:

Note: Exposing the tomcat server directly to HTTP port 80 or HTTPS port 443 will work for lower region or non-mission critical, non sensitive applications, but it is recommended that an application gateway or load balancer be used to front Modelshop access in production environments. If a bridge is used, do not execute the port redirect shown below.

/modelshop/bin
$ sudo redirect_ports.sh

If you need to undo the port redirect, run the following script.

/modelshop/bin
$ sudo unredirect_ports.sh

Create the Modelshop repository¶

Create a directory for Modelshop. The recommended location is /modelshop. Copy the distribution file called modelshop_repository.tar to this directory and untar it:

$ cd /modelshop
$ sudo tar -xvf modelshop_repository.tar

A directory called ‘app’ should be created with the following structure:

modelshop@ubuntu /modelshop/app
$ ls -l
total 9
drwxrwx---+ 1 modelshop modelshop 0    Sep  8 08:28 config
drwxrwx---+ 1 modelshop modelshop 0    Sep  8 08:28 examples
-rwxrwx---+ 1 modelshop modelshop 2262 Jan 28 16:57 modelshop.properties
-rwxrwx---+ 1 modelshop modelshop 507  Sep  8 08:28 modelshop-users.properties
drwxrwx---+ 1 modelshop modelshop 0    Sep  8 08:28 scripts

If you are installing modelshop on premises on a server that will not have access to the Internet, then you will have to install the guide on that server also. Make a directory named “guide”, and copy the distribution file, guideOut.json, to the guide directory:

$ mkdir guide
$ cp $HOME/guideOut.json guide

You may have to change the modelshop directory’s owner, and adjust the app directory’s permissions:

$ cd ..
$ sudo chown -R tomcat:tomcat modelshop
$ cd modelshop
$ sudo chmod -R o+rx app
$ sudo chmod -R o+rx guide #If installing the guide locally

Set Modelshop server options¶

Instance specific options are controlled by the modelshop.properties file located in the instance root - e.g. /modelshop/app/modelshop.properties

Setting	Description	Options
domainName	Name of licensed domain (required)	mycompanydomain
instanceName	Name of instance (required)	ex: demo, production, reporting, test, myInstance
subscriberEmail	Email of the primary license subscriber (required)	my.email@mycompanydomain.com
subscriberKey	A subscriber key if provided.	if server is connected to the internet the key will be retrieved automatically
baseUrl	The base URL for deployment	com.modelshop, com.mycompany
serverUrl	URL for local access	http://localhost:8080/modelshop
publicUrl	URL to access the instance	https://company.modelshop.com/modelshop
modelshop.deployMode	Choose from	design, production
modelshop.users.allowNewRegistration	Allows new users to register for the instance	true, false
modelshop.users.registrationDefaultAccount	The default account for new users	myaccount
modelshop.users.registrationEmailFilter	Semi-colon delimited address filter (ends with)	.mycompany.com;.modelshop.com
modelshop.users.file	User file (if not using the user database option)	${modelshop.repo.root}/modelshop-users.properties
modelshop.config	Location of the instance configuration files $	${modelshop.repo.root}/config
modelshop.data	Location of the instance data cache	${modelshop.repo.root}/data
modelshop.work	Location of temp instance generated files	${modelshop.repo.root}/work
modelshop.templates	Location of generation script templates	Defaults to internal version
modelshop.logLevel	Level of logging	ERROR \| WARNING \| DEBUG \| TRACE
modelshop.cache.encrypted	Set true to encrypt the cache files	true \| false
modelshop.apiTrace	Enable tracing of API calls	OFF \| ALL
modelshop.stackTrace	Enable stack tracing on errors	OFF \| ON
modelshop.guide.url	Optional location for guide	file:///modelshop/guide/guideOut.json
slaask	Enable messages recorded in Slack	true \| false
ping	Enable or disable logout ping from client	true \| false

Note that options set to use ${modelshop.repo.root} will automatically use the installed repo directory (by default /opt/modelshop/app) and do not need to be changed to reflect literal values unless you would like to assign those settings to an alternate location.

Settings such as true, false, off, all, on are case insensitive.

Modelshop license settings¶

License settings are determined by the domainName and subscriberEmail. Trial licenses are assigned automatically upon server startup (valid for 90 days) when a new domainName is presented. If a valid license is found upon startup, the license key will be stored on the server automatically. If the server can not connect to the Modelshop license server, a warning will be logged and you have 30 days to re-connect to the license server.

For installations where the Modelshop server is restricted from connecting to the license server, Modelshop can deliver a custom subscriberKey to set in the modelshop.properties file. For this local license configuration, you may be required to periodically submit encrypted usage information that verifies server instance count and server sizes accessed by the license for audit purposes.

Create initial bootstrap users¶

These installation instructions assume Modelshop’s internal user database (stand-alone). Modelshop supports Single Sign-On integration. Please contact the Modelshop team for instructions for setting up a server for SSO integration.

Edit the modelshop modelshop-users.properties file in the repository root to set the admin password and/or to create initial users. The password for users can be set as clear text, they will be encrypted on Modelshop startup.

In: /modelshop/app/modelshop-users.properties:

admin=secretpassword,enabled,admin,user
anyuser=changeme,enabled,user
guestuser=changeme,enabled,ROLE_GUEST

Change the ownership of all files in the repo to the tomcat user, or the user associated with tomcat. Change the permissions on the modelshop-users.properties file to force read only for the tomcat user:

$ cd /modelshop/app
$ sudo chown –R tomcat:tomcat .
$ sudo chmod 600 modelshop-users.properties

Deploy Modelshop WAR¶

It is recommended that the following steps be managed through a script for repeatability.

Create the images directory in the repository:

$ cd /modelshop
$ sudo mkdir images

Upload the latest modelshop.war file and move or copy it to the images directory. If there already is a modelshop.war file in the images directory, it is recommended that you rename the file to keep it as a backup version of the software.

Shut down tomcat (e.g.):

$ sudo service tomcat stop

Copy the modelshop.war file from the repository images directory to the tomcat webapps directory and set the appropriate owner and permissions (e.g.):

$ sudo rm –r /modelshop/tomcat/webapps/modelshop
$ sudo cp /modelshop/images/modelshop.war /data/tomcat/webapps
$ sudo chmod 600 /modelshop/tomcat/webapps/modelshop.war
$ sudo chown –R tomcat:tomcat /modelshop/tomcat/webapps

Start tomcat on Ubuntu:

$ sudo service tomcat start

Log into Modelshop from the browser (e.g.):

Direct local:   http://localhost:8080/modelshop/#/login

You should see the Modelshop login screen. Unless a new user has been provisioned in the step above, the default bootstrap admin user for Modelshop will be:

Username: admin
Password: admin

It is recommended that the admin password be changed an additional users created before any sensitive data is loaded into Modelshop.

NOTE: GRANTING ADMIN RIGHTS TO A USER SHOULD BE LIMITED TO A SMALL NUMBER OF TRUSTED ADMINISTRATORS. A MODELSHOP USER WITH ADMIN RIGHTS EFFECTIVELY HAS ACCESS TO EVERYTHING INSIDE THE MODELSHOP INSTANCE AND CAN ACCESS MOST RESOURCES GRANTED TO THE OS USER RUNNING THE TOMCAT SERVER. PLEASE ENSURE THAT ADMIN RIGHTS ARE LIMITED TO KEY PERSONNEL AND THAT THE TOMCAT USER ON THE OS DOES NOT HAVE ACCESS TO SENSITIVE RESOURCES YOU WOULD NOT WANT YOUR MODELSHOP ADMIN USERS TO ACCESS. (NORMAL USERS ARE RESTRICTED TO THEIR MODELS OR MODEL RESOURCES SHARED WITH THEM.)

If you are on a server not yet exposed to a browser, test access using the curl command (e.g.):

$ curl http://localhost:8080/modelshop/api/ping/ping

The response should be PONG.

White-labeling the UI¶

On dedicated installations it is possible to add custom icons and logos to white-label the Modelshop user interface. The following files can be added off the repository root:

Location: REPO_ROOT/theme/image/

LOGIN_LOGO.png              Shows when logging in, blue background, recommend white logo, approx 1000x500
MODEL_BROWSER_LOGO.png      Top left corner of model browser, white background, use color logo, approx 500x250
LOADING_LOGO.png            Shown while the model is loading, white background, use color logo, approx 1000x500
INSIDE_MODEL_LOGO.png       Top left corner of open model, dark blue background, use white logo approx 500x250
favicon.ico                 Favicon on browser tab.  Small icon 150x150, color

Location: REPO_ROOT/theme/file

style.css                   A customized CSS forle for colors, fonts, etc
theme.json                  Used to customize local settings

Samples of these files can be found in the theme_example directory under REPO_ROOT

Setting up a Windows Service¶

If the server is being installed on Windows, it is recommended that a Windows service be used to manage the Tomcat server lifecycle. A windows service can be created using the Windows setup utility included with Tomcat.

Run the Tomcat Windows setup utility (this example is for Tomcat 8, the name may be different for other versions of Tomcat):

.\tomcat8w.exe

Modelshop will need additional memory beyond the default memory allocation in order to run effectively. Typically if Modelshop is the primary application on the server it is recommended that up to 75% of the RAM be allocated for the service (for example 24000 Meg on a 32G machine). This utility will add a Tomcat service to Windows services.

Optional Integrations¶

On private domains and on-premise installations, it is possible to extend the capabilities of Modelshop with supported integrations. Custom integrations include deploying custom JDBC drivers for database connectivity, integrating custom Java jars to extend Modelshop’s language and integrating with external analytic servers including H2O.ai and Python.

Installing Custom Java JARs¶

Custom jars are deployed into the Modelshop server simply by adding them to the REPO_ROOT/plugins directory. For example, using the standard installation locations described in this document, the location would be /opt/modelshop/app/plugins

Language Library Extensions¶

Modelshop’s business language comes with an extensive set of language libraries that can be used to perform operations such as math functions, statistical functions or web service integrations. Clients who have a dedicated Modelshop instance can install custom libraries that extend the business language.

Modelshop language extensions have to be compiled as a custom project where each new library implements the com.modelshop.datacore.ModelshopLibrary interface. Building new language extension plugins is beyond the scope of this document. Extension plugins are installed simply by adding them to the /plugins directory when deployed.

Custom JDBC Drivers¶

Modelshop is not shipped with JDBC drivers pre-installed. If the Modelshop instance needs to access a database as a connector, an associated JDBC driver must be installed in the [repo]/plugins directory. The following JDBC drivers have been validated by the Modelshop team and are available for download from the Modelshop distribution website.

Database	Supported Versions	JDBC Driver JAR
My SQL	8.0.18	mysql-connector-java-8.0.18.jar
SQL Server	6.0	sqljdbc42.jar
Postgres	42.2.8	Postgresql-42.2.8.jar
Oracle	19.3	ojdbc8.jar
DB2	11.5	db2jcc4.jar
Hive2	2.6.5 (C6)	HiveJDBC42.jar
Impala	2.6.15 (C6)	ImpalaJDBC42.jar

If the versions included above work for your environment, nothing further is required. In order to deploy an alternative version of a JDBC driver, the driver jar file must be placed in the /plugins library on the server, and the following setting must be created in the modelshop.properties file (example):

modelshop.jdbc.hive2= HiveJDBC4.jar:org.apache.hive.jdbc.HiveDriver

In the format where the key is modelshop.jdbc.XXXX where XXXX is a lowercase version of one of the database types above, the jar file matches the jar file placed in the /plugins directory and the class name after the : refers to the embedded driver that implements the java.sql.Driver interface.

Alternatively, each connector in Modelshop has the option when creating the driver to specify a custom JDBC driver class. The use of database connectors is described in the Modelshop User Guide.

OAUTH2 / OpenID Single Sign-On (SSO)¶

Modelshop supports the ability to authenticate and authorize users using Single Sign-On services available through alternate authorization servers, including Google or custom client SSO implementation that support OAuth2/OpenID authentication.

OAuth2/OpenID can be set up by adding one or more JSON configuration files to the Modelshop repository in the following directory:

$REPO/sso/oauth/ example: /modelshop/app/sso/oauth/google.json

The OAuth setup file should define the following attributes in the form of a JSON structure:

registrationId                The name of the OAuth registration
clientName                    Name of OAuth client
clientId                      ASSIGNED BY AUTHORIZATION PROVIDER
clientSecret                  ASSIGNED BY AUTHORIZATION PROVIDER
clientAuthorizationMethod     "basic"
authorizationGrantType        "authorization_code"
redirectUriTemplate           Endpoint for redirect: "{baseUrl}/oauth2/{registrationId}"
authorizationUri              Authorization endpoint provided by authorization provider
tokenUri                      Token endpoint provided by authorization provider
userInfoUri                   User information endpoint provided by authorization provider
userNameAttributeName         Name of attribute used as the user name
jwkSetUti                     Certs endpoint provided by authorization provider
loginIconUrl                  A URL reference to an icon to be displayed in the SSO login button
primaryLogin                  True or False value - if true, this SSO will be the only login option available
scope                         Array of strings defining scope from [openid, uid, profile, email, address, phone, groups, organization]

A sample configuration file for using Google for single sign on is shown below.

{
      "scope": [
              "openid",
              "profile",
              "email",
              "address",
              "phone"
      ],
      "registrationId": "google",
      "clientName": "Google",
      "clientId": "ASSIGNED_BY_GOOGLE",
      "clientSecret": "ASSIGNED_BY_GOOGLE",
      "clientAuthenticationMethod": "basic",
      "authorizationGrantType": "authorization_code",
      "redirectUriTemplate": "{baseUrl}/oauth2/{registrationId}",
      "authorizationUri": "https://accounts.google.com/o/oauth2/v2/auth",
      "tokenUri": "https://www.googleapis.com/oauth2/v4/token",
      "userInfoUri": "https://www.googleapis.com/oauth2/v3/userinfo",
      "userNameAttributeName": "sub",
      "jwkSetUri": "https://www.googleapis.com/oauth2/v3/certs"
      "loginIconUrl": "https://www.mysite.com/images/google_login.png"
      "primaryLogin": "false"
}

Kerberos Authentication¶

If the database server you are connecting to requires Kerberos authentication, there are additional settings required during server installation.

Security Properties:

The modelshop properties file is where the administrator may configure settings that affect the behavior of the modelshop instance. The file is located in the modelshop repository. For example:

/data/modelshop/app/modelshop.properties

Some of the properties are related to security features:

Property	Description	Values or an Example
modelshop.security.debug	whether to enable debugging	true \| false
modelshop.security.kerberos.ccname	The location of the credential cache file	/opt/modelshop/app/krb5cc_111
javax.security.auth.useSubjectCredsOnly	whether to require a GSS mechanism to obtain necessary credentials from an existing subject	true \| false
java.security.krb5.conf	The location of the configuration file, krb5.conf	/opt/modelshop/app/krb5.conf
javax.net.ssl.trustStore	The location of the trust store where third party certificates are available	/opt/modelshop/app/truststore.ks
javax.net.ssl.trustStoreType	The type of trust store	JKS
javax.net.ssl.trustStorePassword	The trust store password (change to encrypted)	changeIt

Installing the H2O Analytic Server¶

Modelshop provides native integration with the H2O.ai open source machine learning server. The H2O server must be downloaded and installed separately. The 2.0 version of Modelshop requires the 3.22.1.2 release of H2O (latest as of this release).

Instructions for downloading a stand-alone version of the H2O server can be found here:

http://docs.h2o.ai/h2o/latest-stable/h2o-docs/downloading.html

Once installed, start the H20 server from the command line.

java -jar h2o.jar

The H2O Flow user interface can be accessed at the following location by default (a different port may have been selected during installation).

http://localhost:54321/flow/index.html

Of course, you may choose to install H2O on a dedicated server. As model training is a CPU intensive process, it is highly recommended that H2O be installed on a different server than Modelshop.

The link to the H2O server can be set in the modelshop.properties file with the following setting:

modelshop.analyticServers="h2o","H_2_O","http://localhost:54321"

Note, if other analytic servers are installed they would be appended to this setting, e.g.

modelshop.analyticServers="h2o","H_2_O","http://localhost:54321","python","Python","http://54.242.188.26:5000"

Installing the Python Analytic Server¶

The recommended way to set up a Python environment and install most of the necessary dependencies is to use Anaconda. Anaconda by default includes many required dependencies for running the analytic server was well as many popular libraries for scientific and analytic computing in Python. Additional packages required for specific client needs can then be installed with either conda or pip.

Instructions for downloading and installing the Python 3.7 version of Anaconda can be found here:

https://www.anaconda.com/distribution

On linux, download the Anaconda install package using curl:

curl -O https://repo.anaconda.com/archive/Anaconda3-2019.03-Linux-x86_64.sh

Then change the permissions of the file to make it executable with chmod

chmod o+x Anaconda3-2019.03-Linux-x86_64.sh

Then run the shell script and follow the prompts and install Anaconda. If you require an install location other than the default, make note of the location.

./Anaconda3-2019.03-Linux-x86_64.sh

Once the installation is complete, ensure the appropriate environment variables have been set.

python -V

If the python version is not correct, not Anaconda, or you receive an error, set the appropriate variable. Note that if you installed to a location of the installation, you will need to modify the path:

export PATH=~/anaconda3/bin:$PATH

After verifying the proper installation of Anaconda, run the installation script included in the modelshop-python package.

./install.sh

Finally, start the server:

./start.sh

The python server must be registered in the modelshop.properties file, e.g. (each trio of settings represents one analytic server instance)

modelshop.analyticServers="h2o","H_2_O","http://localhost:54321","python","Python","http://54.242.188.26:5000"

Registering an email server¶

When registered, an email server will be used to manage users (sign-up, change password, forgotten password) as well as be made available to models (the Mail functions).

An email server can optionally be registered in the modelshop.properties file:

modelshop.mail.server=pop.gmail.com:995:myemail@mycompany.com:PASSWORD:SSL

PASSWORD should be initially set as clear text. The first time the server starts, it will register a clear text password warning and provide an encrypted version of the password in the log message, you can replace the modelshop.properties file PASSWORD with this encrypted version for security purposes. SSL is true or false

Availability and Staging Architecture Considerations¶

For high availability production requirements, it is recommended that Modelshop be deployed in a high-availability configuration. Since models are memory bound, only one server can be managing a single model at once, but the solution can be designed to support rapid fail-over to a second instance as well as logical balancing of models across 2 or more production servers.

The following availability and development environment servers are recommended based on Customer’s requirements.

x2 production servers, load balanced through Apache bridge, load balancer or similar

x1 development and testing server for model development, Modelshop pre-installs and test automation

In high-availability mode, the load balancer by default should be able to route to either server and handle re-directs. If a request is routed to a server and the model is known to be loaded on one of the other servers, the load-balancer will be re-directed to the correct server.

Appendix A: Modelshop Service Level Agreement¶

Modelshop’s professional license covers full product support for any issues related to platform functionality for as long as the license is current. Support staff will be available 24x7 for emergency escalations, but will respond to most non-critical issues during normal business hours (8am – 5pm ET). Issues can be submitted from the Modelshop application, via email, or by calling a support number.

Models created in Modelshop, either by the customer or by Modelshop as part of a consulting agreement, are not directly covered by support. The behavior of the Modelshop platform, however, is covered by support and Modelshop is obligated to make sure the platform performs as documented.

For Customers electing Customer Hosting, SLAs will be discussed and agreed separately considering factors including availability of Customer managed hardware, Modelshop integration with Customer’s platforms, user access and network availability and outages caused by Customer managed resources (not counted against SLA performance).

The table below describes the Service Level Agreement for Modelshop support:

Issue response and resolution times:

Severity	Criteria	Response Time	Resolution Time
1	Issue that severely impacts production for an API customer such that the system cannot perform its role	1 hour	12 hours
2	Blocking issue that does not have a work-around and prevents forward progress, but allows the production system to continue to perform its role	1 calendar day	2 business days
3	A functional defect that has an effective work-around but degrades the use of the system in a non-trivial way	1 business day	1 week
4	Minor functional defects with an easy work-around or enhancement requests	1 week	discretionary

Response Time – The time from when an issue is reported to Modelshop through an approved channel to when a Modelshop staff member contacts or attempts to contact an appropriate Customer representative

Resolution Time – The time from when an issue is reported to when an issue is resolved or an acceptable work-around is provided. In the case of a work-around, the issue severity will be down-graded but remain open covered by the lower severity SLA.

Availability and response time targets:

	Availability	Response
User Environment	99.5%	1.5 secs
API Servers	99.99%	250 ms

In case availability or response thresholds are not met these will be treated as severity 2 issues. Availability and response time targets are for the base Modelshop service in a Modelshop hosted environment. Outages or high-latency response times that are the direct result of Customer configuration of a model or due to availability or performance problems caused by a Customer Hosted environment will not impact availability and response SLA performance.