Riva Insight On-Premises Setup Guide for Insight 2026.3 or later

Curtis Massie
Curtis Massie
  • Updated

This document explains how to deploy the unified Riva Insight Services project on an on-premises Windows server. The Services project combines Insight, WebAPI (Riva Sync compatibility), and TrackStateService (TSS) into a single Kestrel-based application running as a Windows Service.

 

Prerequisites

  • Windows Server 2022 or later
  • .NET 8.0 Runtime (hosting bundle not required — Kestrel runs standalone)
  • Redis installed and running (required for session sharing and caching)
  • A valid TLS/SSL certificate (if not using a load balancer for TLS termination)
  • Riva Sync installed and configured with a valid .connection file
  • MongoDB instance (required for TrackStateService)

 

A. Install or Setup Prerequisites

  1. Install the ASP.NET Core Hosting Bundle NOTE: Change to .NET Core (without hosting bundle)
  2. Install Redis 
  3. Install MongoDb
  4. Install SSL Certificate
  5. Create Microsoft Graph Registered App
  6. Salesforce Connected App

 

B. Download/Extract Riva Insight Service 

1. Extract the Riva Insight OnPremises Package

  • Download the package from https://dl.rivacrmintegration.com/ (ensure version ois 2026.3 or later)
  • For the downloaded file, go into the properties and select "Unblock"
  • Extract the contents to a location you would like the application hosted (i.e. C:\Riva\Riva Insight\)

C. Riva Insight App Configuration


The configuration settings for the Riva Insight app are configured in appsettings.OnPremises.json. The setting with the file will look something like the following:

{
  "AppSettings": {
    "BasePath": "/insight",
    "Insight.Port": "5001",
    "LoggingLevel": "ERROR",
    "EnvironmentLogPathSuffix": "",
    "Sync.Compatibility.connectionFilePath": "C:\\Riva\\Riva Sync\\Configuration\\user@example.com__www.salesforce.com.connection",
    "Sync.Compatibility.applicationDirectoryInfo": "C:\\Riva\\Riva Sync\\Configuration",
    }
  },
  "CertificateStore": {
      "SslCertificateFindBy": "FindByThumbprint",
      "SslCertificateFindByValue": "<certificate-thumbprint>",
      "SslCertificateStoreName": "My",
      "SslCertificateStoreLocation": "LocalMachine"
    }
  },
  "ConnectionStrings": {
    "RedisConnectionString": "{RedisHost}:6379,password={RedisPassword},abortConnect=false",
    "Insight.Auth.Salesforce.Oauth": "Key={SfConsumerKey};Secret={SfConsumerSecret};CallBackUrl=https://{Domain}:{Insight.Port}{BasePath}/salesforce-oauth;",
    "Insight.Graph.OAuth": "ApplicationId={GraphAppId};Secret={GraphClientSecret};RedirectUri=https://{Domain}:{Insight.Port}{BasePath}/graphfallback/authorize;",
  },
  "MongoDb": {
    "Client": {
      "ConnectionString": "mongodb://username:password@your-mongo-host:27017/Default?tls=false"
    }
  }
}

 

C1. Settings - Base Settings

This is the primary configuration file. It is in root folder of the Insight Application

Setting Description
BasePath The URL path suffix for the application (e.g. /insight, /insight-uat). All requests must include this suffix.
Insight.Port The TCP port Kestrel listens on. Defaults to 5001 if not specified. Must be unique if running multiple Insight instances on the same server.
LoggingLevel   Logging Level  ERROR
 EnvironmentLogPathSuffix   Used to differentiate logs between Insight applications.

NOTE: When setting up multiple Insight services on the same machine, Insight.Port must be different and EnvironmentLogPathSuffix should be changed to differentiate the logs.

C2. Settings - CRM Connection

Required AppSettings

Setting Description
Sync.Compatibility.connectionFilePath Full path to the Riva Sync .connection file for this user/org.
Sync.Compatibility.applicationDirectoryInfo Path to the Riva Sync configuration directory.

C3. Settings - SSL Certificate

Setting Description
SslCertificateFindBy

Determines whether to look up the certificate by name or thumbprint (case-sensitive). Recommended Options: 

  • FindBySubjectName
  • FindByThumbprint
  • FindBySerialNumber
SslCertificateFindByValue The certificate value used to lookup the certificate base on what was set by SslCertificateFindBy.
SslCertificateStoreName

Name of the certificate store. Default is My. Recommended Options:

  • My (Personal) /default
  • Root (Trusted Root Certification Authorities)
  • CA (Intermediate Certification Authorities)
SslCertificateStoreLocation Location of the certificate store. Default is LocalMachine.

C4. Connection String - Redis

Redis is used for session management and distributed caching. All servers in a multi-server setup must point to the same Redis instance.

Look for a connectionstring similar to the following: 

"RedisConnectionString": "{RedisHost}:6379,password={RedisPassword}"

Setting Description
RedisHost Redis host ip address or DNS name.
RedisPort   Redis Port. The default port of 3679 is configured by default.
RedisPassword Redis password.

C5. Connection String - Salesforce App 

Look for a connectionstring similar to the following: 

"Insight.Auth.Salesforce.Oauth": "Key={SfConsumerKey};Secret={SfConsumerSecret};"

Setting Description
SfConsumerKey Redis host ip address or DNS name.
SfConsumerSecret   Redis Port. The default port  of 3679 is configured by default.

 

C6. Connection String - Microsoft Graph App 

Look for a connectionstring similar to the following: 

"Insight.Graph.OAuth": "ApplicationId={GraphAppId};Authority=https://login.microsoftonline.com/{TenantDomainOrID}/oauth2/v2.0"

Setting Description
GraphAppId The application ID of the GRAPH app.
TenantDomainOrID   The Tenant Domain or ID.

C7. Connection String - MongoDB

Look for a connectionstring similar to the following: 

"ConnectionString": "mongodb://{MongoUser}:{MongoPassword}@{mongohost):27017/?tls=false"

Setting Description
MongoHost Mongo host ip address or DNS name.
MongoPort   Mongo Port. The default port of 27017 is configured by default.
MongoUser MongoDB User
MongoPassword   MongoDB Password

Related Article:


D. Start and Verify Riva Insight

If running multiple instances of Insight, each service will needs its own unique name. 

NOTE: When setting up multiple Insight services on the same machine, each Insight Service must be given its own unique name (replace RivaInsightServices in the following steps.

1. Register the Service

Powershell

New-Service -Name "RivaInsightServices" -BinaryPathName "C:\Riva\Insight\Omni.Riva.Insight.Services.exe" -StartupType Automatic
 
Setting Description
-Name Name give to the services (each app requires its own unique name)
-BinaryPathName   Redis Port. The default port  of 3679 is configured by default.

2. Start the Service

The service may be started from the Windows Services control panel, or through PowerShell.

Powershell

Start-Service -Name "RivaInsightServices"
 

If the service fails to start, check the logs located under: ....

%programdata%\riva\insight or %programdata%\riva\insight-{EnvironmentLogPathSuffix}

 

3. Health Check Diagnostics

Load the Insight Diagnostics page to ensure all Insight Services are running. 

To access the diagnostics page, append health.check?diagnostics=true to the end of the Insight URL. 
  E.G.  https://rivainsight.company.local/insight/health.check?diagnostics=true

 
NOTE: If configuration changes are made, the server must be restarted in order for the changes to get picked up. The service may be restarted from the Windows Services control panel, or through PowerShell.

Powershell

Restart-Service -Name "RivaInsightServices";
 

E. Configuring Riva Sync for Riva Insight

F. Load Balancer Configuration

  • Coming soon,