On-Premises Version - Configuring Your Own Launch Server

On-Premises Version - Configuring Your Own Launch Server

Setting Configuration Values

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 in the command line using the --flag=value, --flag2=value2 format. Each listed parameter can also be set as an environment variable. The same parameters (minus the "--") can also be placed in a file called ".env" alongside this executable. In the .env file, omit the "--" characters from the flag names, and separate the options with a new line. The order of precedence is:
  1. Command line flags override environment.
  2. Environment overrides .env file.
  3. .env file overrides defaults.
It's typical to use the .env file to store configuration settings.
Configuration values are sensitive and should be protected.

Example Command Line

$ ./VeracityLaunch-linux [--port 8080] --host=mydomain.com
$ ./VeracityLaunch-linux --help

Example .env File

mongoServer=mongodb://localhost
adminDBName=VTCLXP
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 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 setting is the domain name where the Launch installation can be reached over the network. This should be a publicly routable DNS name, like demo.golaunch.it, or launch.example.com. If Launch is contacted using some other address (for instance the bare server IP), it will respond with an error. This address should not be a URL — it's just the DNS name. It's 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's 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 Launch constructs links to itself, it will use the provided host value from its configuration. If you disable the host header check, it's possible that the links Launch constructs to itself may be incorrect.

Below are examples of valid values:
  1. launch.mycompany.org
  2. veracity.mycompany.com
  3. myveracitylaunch.io
Below are examples of invalid values:
  1. https://testlaunch.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 Launch 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's 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 serves https only if there is a valid sslCert and sslKey setting. If these settings are blank, then 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 Launch 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:
  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 Launch will store all data. Two different installations of Veracity Launch may share a single MongoDB connection by using different admin databases.

Server_Secret

This is a key that is used for various encryption functions internal to Launch. 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.

Uploaded File Storage

When a user uploads learning files, those files are stored and served by the Launch server as part of content playback. In a load balanced environment, each Launch server must have access to these files in order to serve them to clients. 

By default, Launch uses a MongoDB backed filesystem abstraction called "MongoDB GridStore" to store your files. This means that the actual binary of the content is in the MongoDB database. This solution is scalable and performant, and should be sufficient for most deployments. However, when database size (or cost if you're using DBaaS) is a concern you may wish to have Launch store the binary assets elsewhere. In this case, the below settings can be used to cause Launch to host the files on the local filesystem of the webserver. Note that, if you wish to use a load balancer in front of several Launch servers, each server must have access to the files. This means configuring a network file system such as NFS or EFS. 

Setting Name
Discussion
storageDriver
Controls how binary assets are stored. "db" for database or "fs" filesystem. Defaults to 'db'
storageDriverFSRoot
Where on the filesystem the binary assets are stored when the storageDriver is 'fs'. Defaults to //lxpData

Outgoing Email

Veracity Launch 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 the following settings must be populated. Veracity Launch 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 send 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 Launch can serve over SSL, given appropriate certificates. To configure Launch to serve over SSL you must set the following fields. The below configuration assumes there is no proxy between the Launch server and the wider network.

Setting Name
Discussion
protocol
should be https.
port
This is the port that Launch 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 Launch. 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 Launch 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 Launch. In this scenario, the Launch server needs to know that the end user is seeing an SSL connection, even when Launch is not serving SSL. Set the protocol setting to https but leave sslCert and sslKey blank.

WebSockets

Launch uses a WebSocket connection to update various portions of the UI. While WebSockets are optional, it's important that the server understands 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 Launch. If this is not possible, be sure to set enableWebsockets to false.

HTTP Headers

Launch 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 Launch server that the incoming connection was secure, and thus the server will obey the secureCookie setting.

For Launchs 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 Launch 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 Launch 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 Launch 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 Launch 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 Launch writes all log events to the process stdout stream. Your process or service control system is responsible for 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 four 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 four 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 subsystem 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.

Example:
[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

Audit Logging

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 following 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 requestsThis setting will cause the audit logger to save all HTTP requests to the xAPI, including the method, path, and query.
LXP API requests
This setting will cause the audit logger to save all HTTP requests to the 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, ID, and LRS.
User events
Users account events such as created, deleted, locked, unlocked, password reset, login, and 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 revoked, by whom, to whom, and 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.

All Settings

Setting Name
Category
Default
Data Type
Discussion
INSTALL_­NAMEServer SetupString
A name for this installation. Used for reporting functions in a multi-server installation.
SERVER_­NAMEServer SetupString
A name for this server. This will render in the footer. Useful for understanding multi-server environments.
SERVER_­SECRETBasicsYou must change thisString
A value used for various encryption functions. Should be the same between all servers in an installation.
admin­DB­NameBasicsVTCLRSString
The database name to the system level tenant info database.
admin­Notify­UpdatesServer SetupfalseString­Bool
Notify the admin when updates are available.
admin_­emailBasicsString
The email address that identifies the admin user. This value is informational only. To change the actual address, use --setAdminUser=true.
admin_­passBasicsString
The password for the admin user. Do not place this in the .env file. Use the command line with --setAdminUser=true.
brute­Free­RetriesLimits and Rates25Number
The number of free retries before the brute force prevention logic starts limiting the client.
client­Request­QueueSizeServer Setup10Number
How many concurrent commands can each LRS execute per worker.
configBasics.envString
The name of the environment file to use.
debugLoggingfalseString­Bool
Debugging console output. This is overcome by logLevel.
default­User­PermissionsServer Setupadmin.lrs.createString
The default global permissions for users. This is overridden by any specific permissions configuration on a user.
disable­Host­CheckServer SetupfalseString­Bool
Disable checking the host header against the configured host setting.
disable­PluginsdebuggingfalseString­Bool
Prevent the execution of plugins.
disable­Reset­Password­FeedbackServer SetupfalseString­Bool
Prevent the reset password function from displaying any feedback about account status.
disable­SSRF­protectionServer SetupfalseString­Bool
Allow the server to form connections to internal IP addresses.
display­PortBasics3005Number
The user facing port. This can differ from the port setting if there is a proxy server.
domain­RoutingBasicstrueString­Bool
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.
email_­passEmailString
Password on the outgoing email server.
email_­serverEmailString
The address of the SMTP server that the system will use to send emails.
email_­toEmailString
The email address at which the system can reach the system administrator.
email_­userEmailString
Username on the outgoing email server.
enable­WebsocketsServer SetupfalseString­Bool
Enable the WebSocket system for dynamic front end features. You must either use a MongoDB replica set or set the workers setting to 1.
enforce­Limits­Cache­Time30000Number

file­Upload­Size­LimitLimits and Rates100000000Number
The maximum size in bytes for a content package upload.
global­Mongo­TimeoutLimits and Rates10000Number
A global timeout for MongoDB transactions.
host
Basics
local.veracity.it
String
The public facing DNS or IP of the server.
in­Process­JobsFeaturestrueString­Bool
Should this server process the async job queue?
inactive­Account­DisableLimits and RatesHuman Interval
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.
job­FrequencyServer Setup30 secondsHuman Interval
How frequently should the server check for new async jobs in the job pool. Uses a human interval like 30 seconds or 5 minutes.
json­Post­LimitLimits and Rates100kbString
the max size allowed in typical JSON post calls, excluding statement import. example: 100kb, 1mb, or 10gb.
licenseServer SetupString
The license key string provided to you by your sales POC.
lock­After­Failed­Login­AttemptsServer Setup0Number
Lock accounts after X failed login attempts. Use 0 to disable.
log­FormatLogginglinesString
A log formatter. human or lines.
log­LevelLogginginfoString
Set the log level, either trace, debug, info, warn, error, or fatal.
log­SourcesLoggingString
A list of log sources to display. Blank for all.
maximum­Password­LifetimeServer SetupHuman Interval
Force the password from being changed after this period has elapsed.
minimum­Password­LifetimeServer SetupHuman Interval
Prevent the password from being changed again before this period has elapsed.
mongo­ServerBasicsmongodb://localhostString
The full connection string to the Mongo DB server.
no-colorServer SetupString­Bool
Disable console colors.
password­Hash­IterationsServer Setup10000Number
How many times are passwords hashed. Don't change this after install!
password­Retention­CountLimits and Rates5Number
Users may not reuse a password for this many generations.
portBasics3005Number
The actual port that the system will listen on.
protocolBasicshttpString
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.
rate­Limit­WindowLimits and Rates86400Number
The time in seconds that the transaction limit is enforced over.
rebuild­Statements­UI­LimitLimits and Rates50000Number

secure­CookieServer SetupfalseString­Bool
Set the secure flag on the cookies.
session­TimeoutServer Setup0Number
A timeout for the session cookie. Use a number, in milliseconds.
set­Admin­UserBasicsString­Bool
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 line to pass it.
sim­Latencytest0Number
Simulate additional latency for all non-static routes.
ssl­CertServer SetupString
The path (relative to CWD) to the SSL certificate file. Only used when protocol is https.
ssl­KeyServer SetupString
The path (relative to CWD) to the SSL key file. Only used when protocol is https.
stats­Cache­Time180000Number

system­Mongo­ConnectionPool­SizeServer Setup100Number
How many connections to the DB can the system have.
system_­email_­fromEmailString
The address that will appear in the "From" field when the server sends an email.
test­TimeoutTests30000Number
Test timeout.
webRootBasicsString
A root path that all LRS functions will use.
workersLimits and Rates0Number
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.


    • Related Articles

    • Hosting Your Own Launch Server

      Veracity Launch is available for self hosting. Our software is packaged as a standalone executable file with no specific dependencies other than MongoDB. Downloads can be found here: https://build.launch.veracity.it Click here for detailed ...

    • Configuring and Customizing Your Portal

      Overview Once you have created a portal, you can configure the portal settings and add custom branding to match the look and feel of your organization. Review the portal configuration and customization options below. Portal Settings Login to your ...

    • Enrollments, Attempts, and Launches

      It's important to understand Enrollments, Attempts, and Launches to make full use of the Veracity Launch system. Data artifacts associated with these concepts are created automatically, but you must understand their relationships when administering ...

    • LRS Integration / Adding xAPI Support

      Overview Veracity Launch includes some basic login, attempt status, duration and completion reports. More advanced reports and learning analytics using xAPI data can be supported by adding / integrating any xAPI-conformant Learning Record Store ...

    • Using a Delegate™ to Add xAPI Support in Your LMS or Distribute Content

      A Veracity Launch Delegate™ links a content package to set of rules about when, how often, and for how long content is available to an external LMS. Once you've created a Delegate in Veracity Launch, you can download the package and then upload it ...