Configuring Your Own Launch Server

Configuring Your Own Launch Server

Setting Configuration Values

Notes
These settings only apply to on-site installations.
Notes
If you have a hosted SaaS plan, then Veracity manages the settings for your deployment. Contact our support line if you need changes to the settings on your hosted instance.

For an on-premises installation of Veracity Launch, you can change a parameter in the command line using the --flag=value pair format. Or, you can change a parameter by setting an environment variable. You can also change parameters in an .env file (sitting alongside the Launch executable), just omit the -- characters from the flag names and separate the options with a new line. The order of precedence is:
  1. A command line flag overrides an environment variable.
  2. An environment variable overrides an .env file parameter.
  3. An .env file parameter overrides a default value.

Notes
Administrators typically use the .env file to store configuration settings.
Warning
Configuration values are sensitive information — protect them!

Example Command Lines:
$ ./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 Launch settings work well with their default values, and you should only change them if you needed. Other settings are different for every installation and you must configure them to match your IT environment. Below is a discussion of the common settings that all deployments must configure…

host

The host setting is the domain name where users can reach your Launch installation over the network. This should be a publicly-routable DNS name, like demo.golaunch.it, or launch.example.com. If users try to contact Launch with another address (e.g., the bare server IP), then Launch responds with an error.

This address should not be a URL — it's just the DNS name. You can use the server's bare IPV4 address in this field.

Incoming HTTP requests read this value from the host header, so be careful when running the server behind a proxy.

If you can’t make your client offer the correct HTTP header, then disable the server's check of the value: i.e., set disableHostCheck to true. However, when Launch constructs links to itself, it uses the host value in its configuration. So, if you disable the host check, then the links that Launch constructs to itself become incorrect.

Example Valid host Values:
  1. host=launch.mycompany.org
  2. host=veracity.mycompany.com
  3. host=myveracitylaunch.io

Example Invalid host Values:
  1. host=https://testlaunch.com
  2. host=FE80:CD00:0000:0CDE:1257:0000:211E:729C
  3. host=myhostname

port

The port is the port number on which the server listens. When running Launch on a shared server with other web applications, be careful to select a port that no other software uses.

This port appears in all links displayed by the software, unless it's the default port for the chosen protocol.

displayPort

The displayPort is the external-facing port that the client uses to access the system. Unless you are running a proxy, this is the same as the port setting. If you’re running a proxy, then it’s the port on which the proxy listens for client connections.

protocol

The protocol setting controls whether the server speaks HTTP or HTTPS. For historical reasons, the setting also controls which protocol to use to render links to the client. This setting should be either https or http…
  1. http — When the protocol setting is http, the server serves normal HTTP on the selected port, and ignores any values for sslCert or sslKey. Links printed into the UI will use the scheme, http://.

  2. https — When the protocol 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 offers HTTP but prints links to the client with https://. This affects how the server runs behind a proxy.

mongoServer

Veracity uses MongoDB as the primary database. The server won’t start without a functioning MongoDB connection. If the server can’t establish the database connection, then Launch fails, recycles, and tries 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.

Notes
You may need to update MongoDB connection strings that include the term, localhost. If Launch doesn’t connect to your local database, change localhost to 127.0.0.1.

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

adminDBName

The adminDBName 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 but use different admin databases.

Server_Secret

The Server_Secret is the key 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 value.

Changing the Server_Secret value signs-out all users.

Uploaded File Storage

When a user uploads learning files, Veracity Launch stores and serves those files using the server for content playback. In a load-balanced environment, each Launch server must have access to these files to serve them to clients.

By default, Launch uses GridStore — a MongoDB-backed filesystem abstraction — to store your files. This means that the binary of the content is in the MongoDB database. This solution is scalable and performant, and suffices for most deployments.

However, if you’re concerned about database size (or cost, if you're using DBaaS), then you may wish to have Launch store the binary assets elsewhere. In this case, you can use the settings below to cause Launch to host the files on the local filesystem of the webserver.

If you wish to use a load balancer in front of several Launch servers, then 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 Launch stores binary assets: db for database, fs for filesystem. Default is db.
storageDriverFSRoot Where on the filesystem that Launch stores the binary assets when storageDriver is fs. Default is //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, you must populate all the following settings.

Veracity Launch currently supports only SMTP for outgoing messages.

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

Setting Name Discussion
system_email_from The email address that appears in the From field.
email_pass The password for the given SMTP server.
email_server The URL of the SMTP server. For example: smtp.sendgrid.net.
email_to The address used to send notifications to the system administrator.
email_user The username used to access the SMTP server.

Notes
You must populate all five of the above settings to enable outgoing email.

You can verify the administrator email address on the ADMIN > Portal Configuration > Settings page.

Serving SSL

Veracity Launch can serve over Secure Sockets Layer (SSL), given appropriate certificates. To configure Launch to serve over SSL, you must set the following fields:

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

Notes
*This configuration setting assumes you’re not using a proxy between the Launch server and the wider network.

Serving Behind a Proxy

Some organizations choose to use another webserver to proxy HTTP to the Launch. This is useful if you need 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 instead. In this scenario, the Launch server needs to know that the user sees an SSL connection, even when Launch is not serving SSL. Set protocol 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, for the server to work, it still must know whether to expect WebSockets. If you set enableWebsockets to true, then you must also configure the proxy to forward WebSocket connections to Launch. If you can’t, then set enableWebsockets to false.

HTTP Headers

Launch examines the incoming host header to find if the 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 set secureCookie to true, then you must inform the system to trust the upstream proxy. Add a X-Forwarded-Proto header to the HTTP request, and set it to https. This tells the Launch server that the incoming connection is secure, and that the server must obey the secureCookie setting.

For Launch’s inbuilt brute-force protection to work, the server must know the IP address of the client. The incoming IP address triggers brute-force protection, so the server throttles any client hitting the sign-in URL repeatedly. Since the IP address triggers the throttle, the delay won’t affect other clients. If Launch sees the upstream proxy as in incoming IP, then one client could slow-down all the other clients, and Launch users would see a message telling them to wait to sign-in. To inform Launch of the client IP (not the proxy IP), set the header X-Forwarded-For to the client IP address.

Paths

One reason to run Launch behind a proxy is to use the same webserver to host several applications. Set webRoot to 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. Launch also writes some, but not all, events into a log collection in the MongoDB database that you can open from the administrator’s menu. There are four settings that control how Launch structures log information.

Setting Name Discussion
logLevel 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, Veracity Launch formats some data from single events to display on multiple lines, which can break such tools. Set this to lines to strip newlines from log events.
logSources A comma-separated list of log subsystem sources to display. This can help isolate or debug specific components of the system
no-color Launch normally uses ANSI terminal colors to display information. However, some systems cannot display color and show Unicode escape characters instead, making the log difficult to read. Set this to true to disable all color output. 

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

Example Client Log:
{"type": "NotFoundError", "message": null, "when": "2026-05-05T16:55:11.117Z", "context": {"body": {}, ...
{"type": "AccountError", "message": "invalid login", "when": "2026-05-05T16:55:11.182Z", "context": {" ...
{"type": "ClientError", "message": "The statement signed by the signature does not match the statement ...

Audit Logging

Notes
Audit logging is an Enterprise feature.

Enterprise users can activate granular logging of many system events. Veracity Launch records these events into the server logs under the audit log source. The audit logger is a built-in, system-level plugin. You can configure it to log the following event categories:

Event Type Discussion
UI requests HTTP requests to the UI — method, path, and signed-in users.
xAPI requests HTTP requests to the xAPI — method, path, and query.
LXP API requests HTTP requests to the management APIs.
System API HTTP requests to the System management API.
System ODM events System-level data model changes — create, modify, and delete events; for the specific DB entity type and ID.
LRS ODM events LRS-level data model changes — create, modify, and delete events; for the specific DB entity type, ID, and LRS.
User events Users account events — create, delete, lock, unlock, password reset, login, and logout.
Permissions Access control checks — permission, user, entity, and outcome.
Permissions Set Permission changes — permission, by whom, to whom, entity, and granted or revoked.
External Connections When the system reaches-out to another server — purpose, host/URL, protocol, and remote IP.


All Settings

Setting Name Category Default Data Type Discussion
INSTALL_­NAME Server Setup String The name for this installation. Used for reporting functions in a multi-server installation.
SERVER_­NAME Server Setup String The name for this server. Displays in the footer. Useful for understanding multi-server environments.
SERVER_­SECRET Basics You must change this String The value used for various encryption functions. Should be the same between all servers in an installation.
admin­DB­Name Basics VTCLRS String The database name to the system level tenant info database.
admin­Notify­Updates Server Setup false Boolean 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 address, 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.
brute­Free­Retries Limits and Rates 25 Number The number of free retries before the brute-force prevention logic starts limiting the client.
client­Request­QueueSize Server Setup 10 Number How many concurrent commands each LRS can execute, per worker.
config Basics .env String The name of the environment file to use.
debug Logging false Boolean Debugging console output. Overcome by logLevel.
default­User­Permissions Server Setup admin.lrs.create String The default global permissions for users. Overridden by any specific permissions configuration on a user.
disable­Host­Check Server Setup false Boolean Disable checking the host header against the configured host setting.
disable­Plugins debugging false Boolean Prevent the execution of plugins.
disable­Reset­Password­Feedback Server Setup false Boolean Prevent the Reset Password function from displaying any feedback about account status.
disable­SSRF­protection Server Setup false Boolean Allow the server to form connections to internal IP addresses.
display­Port Basics 3005 Number The user-facing port. This can differ from the port setting if using a proxy server.
domain­Routing Basics true Boolean Whether your server uses domain-based routing.
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.
enable­Websockets Server Setup false Boolean Enable the WebSocket system for dynamic front-end features. You must either use a MongoDB replica set or set workers to 1.
enforce­Limits­Cache­Time 30000 Number
file­Upload­Size­Limit Limits and Rates 100000000 Number The maximum size (in bytes) for a content package upload.
global­Mongo­Timeout Limits and Rates 10000 Number The global timeout for MongoDB transactions.
host Basics local.veracity.it String The public-facing DNS or IP of the server.
in­Process­Jobs Features true Boolean Whether this server should process the async job queue.
inactive­Account­Disable Limits and Rates Human Interval The time limit when to lock a user account if the user doesn’t sign-in. A human interval, like 30 years or 8 weeks.
job­Frequency Server Setup 30 seconds Human Interval The number of times the server checks for new async jobs in the job pool. A human interval like 30 seconds or 5 minutes.
json­Post­Limit Limits and Rates 100kb String The maximum size in typical JSON post calls, excluding statement import. Example: 100kb, 1mb, or 10gb.
license Server Setup String The license key string provided by your sales POC.
lock­After­Failed­Login­Attempts Server Setup 0 Number The number of failed sign-in attempts until locking an account. Enter 0 to disable.
log­Format Logging lines String The format of the log: human or lines.
log­Level Logging info String The level of the log, either trace, debug, info, warn, error, or fatal.
log­Sources Logging String The list of log sources to display. Blank for all.
maximum­Password­Lifetime Server Setup Human Interval Force the user to change their password after this period elapses.
minimum­Password­Lifetime Server Setup Human Interval Prevent the user from changing their password again until this period elapses.
mongo­Server Basics mongodb://localhost String The full connection string to the Mongo DB server.
no-color Server Setup String­Bool Disable console colors.
password­Hash­Iterations Server Setup 10000 Number The number of times to hash passwords. Don't change this after install!
password­Retention­Count Limits and Rates 5 Number After this many generations, users may not reuse a password.
port Basics 3005 Number The actual port that the system listens on.
protocol Basics http String The user-facing protocol. The server uses HTTP if http, and HTTPS only if https and the sslKey and sslCert are set.
rate­Limit­Window Limits and Rates 86400 Number The time (in seconds) of transaction limit enforcement.
rebuild­Statements­UI­Limit Limits and Rates 50000 Number
secure­Cookie Server Setup false Boolean Set the secure flag on the cookies.
session­Timeout Server Setup 0 Number The timeout for the session cookie (in milliseconds).
set­Admin­User Basics Boolean 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­Latency Tests 0 Number Simulate additional latency for all non-static routes.
ssl­Cert Server Setup String The path (relative to CWD) to the SSL certificate file. Only used when protocol is https.
ssl­Key Server Setup String The path (relative to CWD) to the SSL key file. Only used when protocol is https.
stats­Cache­Time 180000 Number
system­Mongo­Connection­Pool­Size Server Setup 100 Number The number of connections to the DB that the system can have.
system_­email_­from Email String The address that appears in the From field when the server sends an email.
test­Timeout Tests 30000 Number Test timeout.
webRoot Basics String The root path that all functions will use.
workers Limits and Rates 0 Number The number of processors to use. If unset (or set to 0), then it uses the number of logical cores on the server. Lite mode limits to 1.



    • Related Articles

    • Hosting Your Own Launch Server

      You can host Veracity Launch on your own server! We offer a version of our software that we packaged as a standalone executable file with no specific dependencies, other than MongoDB. Simple Installation – Default Configuration Running Veracity ...

    • Configuring and Customizing Your Portal

      Once you create a portal, you can configure your portal to add custom branding to match the look-and-feel of your organization. The LMS administrator’s Configuration page has five options: Portal Settings — Manage portal configuration Upload Logo — ...

    • Content Format Support

      Learning Standards When you Add Content to your portal and select Upload SCORM or xAPI, Launch scans the package, detects the format, and pre-configures your new content according to the learning technology standard. cmi5 Although you select Upload ...

    • API Integrations

      You can use Veracity Launch to play content from your LMS. You create a launch link in our API and then forward the learner to a location in our API. The learner experiences the content seamlessly, then returns to the callback address of your choice. ...

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

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