Configuration

Setting Configuration Values

It's typical to use the .env file to store configuration settings.

These settings only apply to on site installations. When using a hosted SaaS plan, Veracity will manage the settings for your deployment. Contact support if you require modifications to the settings on your hosted instance.

You can set parameters using the --flag=value --flag2=value2 format. Each listed parameter can also be placed in a file called .env along side this executable. In the .env file, omit the `--` characters from the flag names, and separate the options with a new line. The same parameters (minus the `--`) can be set as environment variables. The order of precedence is command line flags override environment, environment overrides .env file, .env file overrides defaults.

Configuration values are sensitive and should be protected. 

Example Command Line:

$ ./lrs2 [--port 8080] --disableAccountCreation
$ ./lrs2 --help

Example .env file

1. inProcessJobs=true
2. selfServiceAccounts=false
3. mongoServer=mongodb://localhost
4. adminDBName=VTCLRS
5. elasticSearchServer=
6. host=local.veracity.it
7. port=80
8. displayPort=80
9. protocol=http
10. domainRouting=false
11. SERVER_SECRET=9bcf20cc-b326-4d6f-9691-8c384e5dfbf8

Required Settings

Most Veracity settings work well with their default values, and you should only change them if you have need to do so. Other settings are different for every installation, and need to be configured to match your IT environment. Below is a discussion of the common settings that all deployments will need to configure.

host

The host settings is the domain name where the LRS installation can be reached over the network. This should be a publicly routable DNS name, like demo.lrs.io, or lrs.example.com. If the LRS is contacted using some other address (for instance the bare server IP), the LRS will respond with an error. This address should NOT be a URL - it is just the DNS name. It is possible to use the server's bare IPV4 address in this field. This value is read from the host header of incoming HTTP requests, so you should be careful when running the server behind a proxy. If it is impossible to make your clients provide the correct http header, then you can disable the server's check of the value. To disable the host header check, set disableHostCheck to true. Note that when the LRS constructs links to itself, it will use the provided host value from it's configuration. If you disable the host header check, it is possible that the links the LRS constructs to itself (embeddable chart and dashboard links, the "more" link in an xAPI statement response, and others) may be incorrect. 

Below are examples of valid values

1. lrs.mycompany.org
   
2. veracity.mycompany.com
   
3. myveracitylrs.io
   

Below are examples of invalid values

1. https://testlrs.com
   
2. FE80:CD00:0000:0CDE:1257:0000:211E:729C
   
3. myhostname

port

This is the port number on which the server will actually listen. When running the LRS on a shared server that contains other web applications, you must be careful to select a port that is not in use by other software. This port will appear in all links displayed by the software, unless it is the default port for the chosen protocol. 

displayPort

This is the external facing port that a client will use to access the system. Unless you are running a proxy, this will equal the port setting. If you are running a proxy, it will be the port on which the proxy listens for client connections.

protocol

This setting controls which protocol, HTTP or HTTPS,  the server will speak. For historical reasons, it also controls what protocol will be used to render links to the client. This setting should be either "https" or "http". 

http

When the setting is "http", the server will serve normal http on the selected port. Any config values for sslCert or sslKey will be ignored. Links printed into the UI will use the scheme "http://"

https

When the setting is "https" the server serve https only if their is a valid sslCert and sslKey setting. If these settings are blank, the server will serve http, but will print links to the client with "https://". This has some ramifications for running the server behind a proxy

mongoServer

Veracity uses MongoDB as the primary database. The server will not start up without a functioning MongoDB connection. If the database connection cannot be established, the LRS will fail, recycle and try again until the database becomes available. The MongoDB  connection string contains information about the location of the server, the credentials to use to connect, and settings related to the database connection. The mongoServer should NOT include a database name, or trailing slash. 

Examples:

1. mongodb://localhost
   
2. mongodb://dbUserName:password@local.veracity.it:27017
   
3. mongodb+srv://root:xxxxxxx@test.xxxxx.mongodb.net

adminDBName

This is the name of the database in which the LRS will store all data unrelated to an individual tenant. 2 different installations of Veracity may share a single MongoDB connection by using different admin databases. 

elasticSearchServer

This setting is the connection string to Elasticsearch. Connecting to Elasticsearch is optional. Because the default of this setting is "http://localhost:9200", you must explicitly set the value to nothing in order to disable the Elastic connection. 

Server_Secret

This is a key that is used for various encryption functions internal to the LRS. This should be a random string of characters. In a multi-server environment, each server should share the same random value. Changing this setting will log out all users. 

Examples:

1. http://elastic:w3FKZHaoREVf4EA8S6yf@localhost:9200
   
2. http://localhost:9200

Outgoing Email 

Veracity can send emails to verify user accounts and support password reset. The system can also notify the administrator in the case of an unexpected restart of the software ( usually caused by an error). To configure outgoing email, all of the following settings must be populated. Veracity currently supports only SMTP for outgoing messages. 

Some STMP processors require that the "system_email_from" address be from a validated address. Check with your SMTP provider.

Setting Name	Discussion
system_email_from	This is the email address that will appear in the "from" field
email_pass	This is the password for the given SMTP server
email_server	This is the URL of the SMTP server. For example - smtp.sendgrid.net
email_to	This address is used to sent notifications to the system administrator
email_user	The username used to access the SMTP server

All five of the above settings must be populated to enable outgoing email. You can verify that outgoing email is configured by checking the "current configuration" page from the administrative tools

Serving SSL

Veracity can serve over SSL, given appropriate certificates. To configure Veracity to serve over SSL you must set the follow fields. The below configuration assumes there is no proxy between the LRS and the wider network.

Setting Name	Discussion
protocol	should be "https"
port	This is the port that the LRS actually listens on. Generally this would be 443 for SSL
displayPort	When not behind a proxy, the displayPort should match the port value
sslCert	This is the path (relative to the working directory) to the SSL certificate file. This file should be in the PEM format, and may contain additional chained certificates. For example: testcerts/certificate.crt
sslKey	This is the private key associated with the certificate in the .crt file.   This file should be in the PEM format. For example: testcerts/privatekey.key

Example certificate and key files are provided in the article attachments

Serving Behind a Proxy 

Some organizations will choose to use another webserver to proxy HTTP to the LRS. This is useful in a case where you wish for more granular control over the HTTP requests, such as to set specific SSL configurations, to add additional headers, or for logging purposes. There are several considerations when running the LRS behind a proxy. 

SSL termination

One common use case is to configure the proxy to terminate the SSL connection to the client, and form a regular HTTP connection to the LRS. In this scenario, the LRS needs to know that the end user is seeing an SSL connection, even when the LRS is not serving SSL. Set the protocol setting to "https", but leave sslCert and sslKey blank. 

Streaming and file sizes 

The LRS has many functions intended to work for arbitrarily large data sizes, such as database backup or xAPI statement JSON upload. It's important to prevent your proxy server from buffering requests and responses, or some data loads my exceed the buffer limits and fail. Additionally, some data is streamed down to the client as it is processed. The software is designed such that most long running exports of reports or xAPI statements should begin downloading immediately, and new bytes are returned to the client as they are available. With buffering enabled in your proxy, no bytes will be returned to the client until the entire export completes. This can cause the client to abort the connection after no bytes are received in a given time, thus making it impossible to retrieve long running reports. 

Websockets

The LRS uses a Websocket connection to update various portions of the UI. While websockets are optional, it's important that the server understand whether or not to expect websockets to work. If enableWebsockets is set to "true", then the proxy must be configured to forward websocket connections to the LRS. If this is not possible, be sure to set enableWebsockets to "false".

HTTP Headers

The LRS will examine the incoming Host header to determine that the end client accessed the site from the expected domain. Set your proxy to echo the host header as received from the client, not to overwrite the header with the internal network host value. 

If you've set secureCookie to true, you'll need to inform the system that the upstream proxy is trusted. To do so, set a header on the HTTP request called "X-Forwarded-Proto" and make the value "https". This will inform the LRS server that the incoming connection was secure, and thus the server will obey the secureCookie setting.

In order for the LRSs inbuilt brute force protection to work, the IP address of the end client needs to be known to the server. Brute force protection is keyed by the incoming IP address, so a client hitting the login URL repeatedly will be throttled. Since the throttle is controlled by the IP, other clients are not affected by the delay. If the LRS sees the upstream proxy as in incoming IP, then one client may cause all clients to be slowed down, and users may experience a message telling them to wait to log in. To inform the LRS of the actual client IP, not the proxy's IP, set the header "X-Forwarded-For" to the actual client IP address. 

Paths

One reason to run the LRS behind a proxy is to use the same webserver to host multiple applications. Set the setting webRoot to be a path on your server, and configure your proxy to forward only those paths to the LRS application. 

Example nGinX location block

1. location /
2.                 {
3.                         proxy_pass http://localhost:3005/;
4.                         proxy_set_header Host            $host;
5.                         proxy_set_header X-Forwarded-For $remote_addr;
6.                         proxy_http_version 1.1;
7.                         proxy_set_header Upgrade $http_upgrade;
8.                         proxy_set_header Connection "Upgrade";
9.                         proxy_set_header X-Forwarded-Proto $scheme;
10.                         proxy_buffering                 off;
11.                         proxy_request_buffering off;
12.                         proxy_read_timeout              18000s;
13.                         proxy_send_timeout              18000s;
14.                 }

Logging 

Veracity writes all log events to the process stdout stream. Your process or service control system is responsible form writing this information to disk, a database, or otherwise storing the events. Some, but not all, events are also written into a logs collection in the MongoDB database, and can be viewed from the administrative UI. There are 4 settings that control how the log information is structured.

Setting Name	Discussion
logLevel	This is the logging verbosity. Either "debug", "info", "warning", or "error"
logFormat	Either "human" or "lines". Some log management tools generate separate events for each newline in the output stream. In human mode, some data from single events is formatted to display on multiple lines, which can break such tools. Set the logFormat to lines to strip newlines from log events.
logSources	This is a comma separated list of log subsystem sources to display. This is useful when trying to isolate or debug specific components of the system
no-color	The LRS will normally use  ANSI terminal colors to display information. Set this to true to disable all color output. Some systems are not capable of displaying this color, and will show many unicode escape characters instead of the coloring, making it difficult to view the logs.

Configuring a process control system to forward logs is beyond the scope of this documentation. 

Log Format

Each line of a logged event is formatted in 4 fixed width columns. The first column is the ID of the worker thread that sent the message. The second is the message level - how important the message is. The third column is the log source - which sub system generated the message. The logs can be filtered by both the source and level with the logSource and logLevel settings. The remainder of the line is the raw string of the message. This may or may not include formatted text or JSON data.

[M] info plugins Found Plugin Dashboard C:\Development\vtc2\lrs2\plugins\netc-dashboards\dashboards\instructor\navyInstructorActivities.js
[M] info plugins Found Plugin Dashboard C:\Development\vtc2\lrs2\plugins\netc-dashboards\dashboards\student\netcStudentActivities.js
[M] info websock Starting socket server
[M] info system Listening on 3005
[M] info system Startup Complete
[M] info audit System System Start
[M] info audit EXTERNAL_CONNECTION 54.209.2.187:443
[M] info audit UI GET /lrs/test-buck/content/create/ admin@example.com
[M] info audit ACCESS lrs.content.create 640741e6240cc64d0857566f lrs.js admin@example.com true

Auditing

Audit logging is an Enterprise feature.

Enterprise users can activate granular logging of many system events. These events will be printed into the server logs under the "audit" log source. The audit logger is a built-in, system level plugin. It can be configured to log the follow event categories

Event Type	Discussion
UI requests	This setting will cause the audit logger to save all HTTP requests to the UI, including the method, path and any logged in user
xAPI requests	This setting will cause the audit logger to save all HTTP requests to the xAPI, including the method and path, and query
LRS API requests	This setting will cause the audit logger to save all HTTP requests to the LRS management APIs
System API	This setting will cause the audit logger to save all HTTP requests to the System management API
System ODM events	Log all system level data model changes. All DB entities will report created, modify and delete events for the specific entity type and ID
LRS ODM events	Log all LRS level data model changes. All DB entities will report created, modify and delete events for the specific entity type and ID and LRS
User events	Users account events such as created, deleted, locked, unlocked, password reset, login, logout
Permissions	This system will record all access control checks including what permission was requested, by who, on what entity and what was the outcome
Permissions Set	The system will record all modifications to permissions, including what permissions were granted and revokes, by whom, to whom, on what entity
External Connections	The system reached out to another server for some purpose. The log will contain the purpose, host/url, protocol and remote IP.

Self Service User Accounts

This section describes topics related to allowing users to manage their own accounts. This includes password reset, LRS creation, and account creation. Generally, an Enterprise install will be configured for only the system administrator to create LRS and user accounts. It is possible to configure the system to allow self registration and LRS creation. 

Self service account creation and password reset requires outgoing email to be enabled.

The below table shows the recommended settings for an enterprise deployment. This will allow existing accounts to request password reset emails. Users may not self register to the system, and users may not create their own LRSs. To allow specific users to create or access an LRS, use the system level permission system.

Setting Name	Recommended value
selfServiceAccounts	true
disableAccountCreation	true
defaultUserPermissions	(empty string)

The system can also be configured into a more permissive state, where users can create accounts for themselves and create their own LRS. This configuration supports a SaaS deployment similar to ours at lrs.io. 

Enterprise customers should restrict network access to the LRS when in this state to prevent unauthorized users from creating accounts and LRSs

Enterprise customers are prohibited from charging for access to their LRS. Contact Veracity for the exact terms of the Enterprise license.

Setting Name	Recommended value
selfServiceAccounts	true
disableAccountCreation	false
defaultUserPermissions	system.lrs.create

All Settings 

Setting Name	Category	Default	Data Type
INSTALL_NAME	Server Setup		String
A name for this installation. Used for reporting functions in a multi server install.
SERVER_NAME	Server Setup		String
A name for this server. This will render in the footer. Useful for understanding multi server environments
SERVER_SECRET	Basics	You must change this	String
A value used for various encryption functions. Should be the same between all servers in an installation.
adminDBName	Basics	VTCLRS	String
The database name to the system level tenant info database.
adminNotifyUpdates	Server Setup	FALSE	StringBool
Notify the Admin when updates are available
admin_email	Basics		String
The email address that identifies the admin user. This value is informational only - to change the actual use --setAdminUser=true
admin_pass	Basics		String
The password for the admin user. DO NOT PLACE THIS IN THE .ENV file. Use the command line with --setAdminUser=true
analyticsRetryTimeout	Analytics	5000	Number
The time in MS before the client is signaled that the processor is working, and to try back later
autoIndexRebuildLimit	Limits and Rates	30000	Number
When indexes are stale, LRSs with less than this many statements will be automatically upgraded.
backupEncryptKey		fa299d32-96e2-43bf-aad7-2e61a96a8ddb	String
This key is used to encrypt LRS backups.
bruteFreeRetries	Limits and Rates	25	Number
The number of free retries before the brute force prevention logic start limiting the client.
clientRequestQueueSize	Server Setup	10	Number
How many concurrent commands can each LRS execute per worker: Default: 10
config	Basics	.env	String
The name of the environment file to use. Defaults to .env
debug	Logging	FALSE	StringBool
Debugging console output (this is overcome by logLevel)
defaultUserPermissions	Server Setup	admin.lrs.create	String
The default global permissions for users. This is overridden by any specific permissions configuration on a user
disableAccountCreation	Features	FALSE	StringBool
Prevent account creation.
disableAnalyticsCache	Debugging	FALSE	StringBool
Disable caching of the results for the analytics dashboards
disableHostCheck	Server Setup	FALSE	StringBool
Disable checking the host header against the configured host setting.
disablePlugins	debugging	FALSE	StringBool
Prevent the execution of plugins
disableResetPasswordFeedback	Server Setup	FALSE	StringBool
Prevent the reset password function from displaying any feedback about account status.
disableSSRFprotection	Server Setup	FALSE	StringBool
Allow the server to form connections to internal IP addresses
displayPort	Basics	3005	Number
The user facing port. This can differ from the `port` setting if there is a proxy server.
domainRouting	Basics	TRUE	StringBool
Whether or not your server will use domain based routing. This means that the xAPI address will be yourlrs.lrs.io/xapi, or lrs.io/yourlrs/xapi
elasticMissingRatioError	Analytics	0.99	Number
When determining if an ElasticSearch index is `healthy`, it must have this ratio of statements to the MongoDB count.
elasticReconnectTimeout	Analytics	30 seconds	HumanInterval
A when a connection to ES fails, how long should the server wait before trying again? (as a human interval, i.e "1 minute")
elasticSearchServer	Analytics		String
The full URL to the ElasticSearch server. Please be sure to use version 7.x of ElasticSearch
elasticTimeout	Analytics	20s	String
A timeout for ElasticSearch Queries
email_pass	Email		String
Password on the outgoing email server
email_server	Email		String
The address of the SMTP server that the system will use to send emails.
email_to	Email		String
The email address at which the system can reach the system administrator
email_user	Email		String
Username on the outgoing email server
enableWebsockets	Server Setup	FALSE	StringBool
Enable the websocket system for dynamic front end features. You must either use a MongodDB replicaSet or set the workers setting to 1
enforceLimitsCacheTime		30000	Number
enforcePasswordComplexity	Server Setup	FALSE	StringBool
Require complex passwords
esDynamicExtensions	Analytics	TRUE	String
How are dynamic extensions treated? "true" for regular ES dynamic mapping or "runtime" to use runtime mapping.
esIndexExtensions	Analytics	TRUE	StringBool
Should xAPI extensions be included in the Elasticsearch mapping? This can cause document rejection if you have many different extensions in a dataset.
esKeywordMaxLength	Analytics	256	Number
The maximum length beyond which similar strings will be assumed the same in the Elasticsearch mapping
expireMoreLinksAfter	Server Setup	86400000	Number
When to purge the More links from the xAPI
fetchLRSRoutingCacheTime		5000	Number
fileUploadSizeLimit	Limits and Rates	100000000	Number
The maximum size in bytes for a content package upload
forcePortalLaunchCookie	Server Setup	FALSE	StringBool
Require the portal cookie, even for cross domain content
fullTextQueryLimit	Limits and Rates	100	Number
The limit of results for full text searches in the statement viewer.
generateStatementsIterations	Limits and Rates	30	Number
The number of iterations for the statement generation function.
globalMongoTimeout	Limits and Rates	10000	Number
A global timeout for MongoDB transactions.
host	Basics	local.veracity.it	String
The public facing DNS or IP of the server.
inProcessJobs	Features	TRUE	StringBool
Should this server process the async job queue?
inactiveAccountDisable	Limits and Rates		HumanInterval
A human interval like `30 years` or `eight weeks`. The amount of time where a user account will be locked if the user does not log in.
jobFrequency	Server Setup	30 seconds	HumanInterval
How frequently should the server check for new async jobs in the job pool. Uses a `human interval` like `30 seconds` or `5 minutes`
jsonPostLimit	Limits and Rates	100kb	String
the max size allowed in typical JSON post calls, excluding statement import. example: 100kb, 1mb, 10gb. Default, 100kb
license	Server Setup		String
The license key string provided to you by your sales POC.
lockAfterFailedLoginAttempts	Server Setup	0	Number
Lock accounts after X failed login attempts. User 0 to disable
logFormat	Logging	lines	String
A log formatter. "human" or "lines"
logLevel	Logging	info	String
Set the log level, either trace,debug,info,warn,error, or fatal
logSources	Logging		String
a list of log sources to display. Blank for all
maxVQLWindowSize	Limits and Rates	10000	Number
The maximum number of results returned from any VQL query
maximumPasswordLifetime	Server Setup		HumanInterval
force the password from being changed after this period has elapsed. . Human Interval
minimumPasswordLifetime	Server Setup		HumanInterval
prevent the password from being changed again before this period has elapsed. Human Interval
mongoServer	Basics	mongodb://localhost	String
The full connection string to the Mongo DB server
no-color	Server Setup		StringBool
Disable console colors
passwordHashIterations	Server Setup	10000	Number
How many times are passwords hashed. Don't change this after install!
passwordRetentionCount	Limits and Rates	5	Number
Users may not reuse a password for this many generations
port	Basics	3005	Number
The actual port that the system will listen on.
protocol	Basics	http	String
The user facing protocol. Note that server will serve with HTTP if this is HTTP, and HTTPS only if this is HTTPS and the SSLKey and SSLCert are set
rateLimitWindow	Limits and Rates	86400	Number
The amount of time in seconds that the transaction limit is enforced over.
rebuildStatementsUILimit	Limits and Rates	50000	Number
recaptcha_site_key	Server Setup		String
The site key for Googles Recaptcha system. Leave this blank to disable captchas.
secureCookie	Server Setup	FALSE	StringBool
Set the secure flag on the cookies.
selfServiceAccounts	Features	TRUE	StringBool
Can users sign up for an account on their own?
sessionTimeout	Server Setup	0	Number
A timeout for the session cookie. Use a number of milliseconds
setAdminUser	Basics		StringBool
Update the database to reflect the values stored in --admin_email and --admin_pass. Do not place the password in the env file. Use the command like to pass it.
simLatency	test	0	Number
Simulate additional latency for all non static routes
sslCert	Server Setup		String
The path (relative to CWD) to the SSL certificate file. Only used when `protocol` is HTTPS
sslKey	Server Setup		String
The path (relative to CWD) to the SSL key file. Only used when `protocol` is HTTPS
statementDefaultLimit	Limits and Rates	300	Number
The default number of statements when `limit` is not set in the xAPI.
statementMaxLimit	Limits and Rates	10000	Number
The max `limit` that the server will support in the xAPI.
statsCacheTime		180000	Number
systemMongoConnectionPoolSize	Server Setup	100	Number
How many connections to the DB can the system: Default: 100
system_email_from	Email		String
The address that will appear in the `from` field when the server sends an email.
testTimeout	Tests	30000	Number
Test Timeout
webRoot	Basics		String
A root path that all LRS functions will use
workers	Limits and Rates	0	Number
The number of processors to use. If unset (or set to 0), will use the number of logical cores on the server. Lite mode limits to 1.
xapiAttachmentSizeLimit	Limits and Rates	1000000	Number
The maximum size in bytes for an xAPI attachment
passwordDictionary	Server Setup		String
*New in 1.14* a path (either absolute or relative to the CWD) to a file of newline delimited passwords that should be blacklisted (user cannot choose these passwords)

• Related Articles

• Installation

  The process for installing the Lite or Enterprise version of the LRS is quite similar. First, you'll need to download and extract the software. Veracity Learning LRS is cross-platform. You can run it on Windows or Linux. If you need to run the server ...

• Single Sign On (SSO) Integration

  Veracity can integrate with your single sign on provider using OpenID Connect or Security Assertion Markup Language (SAML). This integration allows your enterprise users to log into the LRS user interface without providing a password. Integrating a ...

• Custom Dashboards, Graphs and Analytics Processors

  Veracity Learning offers several ways to generate custom dashboards. At the most basic level, you can place widgets (graphs or tables) on a dashboard page. Each widget is customizable with a set of options like what actor, what object or what verb to ...

• LMS Integration

  The Veracity Learning offers seamless integration with your LMS to allow instructors and students to access the services of the LRS without leaving their LMS environment. This is accomplished via LTI (Learning Tools Interoperability), a standard from ...

• Elasticsearch Integration

  Overview The LRS can accelerate its dashboard and statement viewer by leveraging Elasticsearch in addition to MongoDB. When configured with the optional Elasticsearch connection, the LRS will synchronize xAPI statements in real time between these two ...