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
$ ./lrs2 --help
Example .env file
- inProcessJobs=true
- selfServiceAccounts=false
- mongoServer=mongodb://localhost
- adminDBName=VTCLRS
- elasticSearchServer=
- host=local.veracity.it
- port=80
- displayPort=80
- protocol=http
- domainRouting=false
- 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
- lrs.mycompany.org
- veracity.mycompany.com
- myveracitylrs.io
Below are examples of invalid values
- https://testlrs.com
- FE80:CD00:0000:0CDE:1257:0000:211E:729C
- 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.
MongoDB connection strings that include the term "localhost" may need to be updated. If the LRS does not connect to your local database, please change "localhost" to "127.0.0.1".
Examples:
- mongodb://localhost
- mongodb://dbUserName:password@local.veracity.it:27017
- 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:
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
- location /
- {
- proxy_pass http://localhost:3005/;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-For $remote_addr;
- proxy_http_version 1.1;
- proxy_set_header Upgrade $http_upgrade;
- proxy_set_header Connection "Upgrade";
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_buffering off;
- proxy_request_buffering off;
- proxy_read_timeout 18000s;
- proxy_send_timeout 18000s;
- }
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
[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 |
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 ...Power BI Integration
Integration with Power BI Integration is accomplished by pulling a saved statement viewer report into PowerBI. Before you can do this, you'll need an API key. Navigate to "All Mangement Tools" then find "Security" Click "API Keys" Click "Create New ...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 ...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 ...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 ...