Running DarkLight

Start DarkLight by double-clicking the DarkLight file in your install location (probably \users\<yourusername>\apps\DarkLight\app) or by using the shortcut that may have been installed into your Start menu or desktop.


DarkLight can optionally show a text-based console window that shows the "behind-the-scenes" logging information and allows commands to be sent to the server. This can be helpful in trouble-shooting the application. Each operating system invokes the console in different ways.

  • Windows: The console is on by default. The console can be toggled on and off by navigating to the directory where the DarkLight.exe file is, and editing DarkLight.ini in a text editor. To make the console show up, add -console on the line above -vmargs. To make the console not show up, remove the -console line from the file. This file is read at application startup.
  • macOS: The file is a bundle of files and folders called a Package. To run DarkLight with the console open, right-click on and choose Show Package Contents. Navigate to Contents→MacOS and double-click on DarkLight. This will run the application and open up a Terminal console.
  • Linux Server: The console will only show up if the application is run from a command line prompt (recommended), such as in the Terminal app. Navigate to your install directory, and launch the app with ./DLServer. The Terminal window will show the console output. See more tips on running the server below.

When DarkLight runs it will ask you for a workspace. This is the location where configuration files for each project are stored, e.g., ontologies, reify configurations, playbooks, databases, etc. Choose a location on the file system and click OK to load the workspace. The next time you run DarkLight, the workspace you last used will automatically be started. Once DarkLight is running, you can change to a different workspace with the File→Switch Workspace menu item.

Where the data is stored

Nerdy Note: The workspace path is stored in your system's user folder at <user>/champion/server/champion.settings if you ever need to edit it manually with a text editor.

To Create a new workspace, enter the new path where you want the new workspace. When you click OK, DarkLight will prompt you that this location does not exist and confirm that you want to create a new workspace there. No spaces can be in the path to the workspace or a bug in ActiveMQ will prevent DarkLight from starting.

DarkLight will need to restart when a new workspace is chosen.

Server Version: Set the workspace on the server version with workspace load. Starting in version 3.5.0, new workspaces are automatically configured to receive connections from clients. (Prior versions needed to enter remote start in the console when creating a new workspace.)

If you see the message "Connecting to Server" for more than 3 minutes:

  • Expired License: If you have successfully run DarkLight before and were given a trial license, this is most likely caused because your license file has expired. Contact Support to request a new license file, then use it to replace the darklight.lic file in the same directory as your executable.
  • Not Enough RAM: If this is the first time you have run DarkLight, it may be because the system does not have enough RAM to start the database. Ensure the system has at least 8GB of RAM and try again.
  • Spaces in the Workspace Path: Ensure that the full path to the workspace you are trying to load does not have any spaces in it. If you are unsure which workspace is being loaded, type workspace active into the console, or open the file in your user folder at <user>/champion/server/champion.settings in a text editor and look at the value for load.workspace= (this file can be manually edited, too, and will be read the next time DarkLight starts up).

DarkLight comes with several pre-configured perspectives, including Reify, Ontologies, PRO Playbooks and several others. In a new workspace, only Review opens automatically. However, when opening the demo workspace, all of the perspectives are open. To open the other perspectives in a new workspace use the plus button in the upper right corner, and drag them to rearrange as desired.

DarkLight is configured to automatically check with the update server at each time it is run. When an update is available, a dialog will ask if you would like to upgrade during the startup process. If you choose to upgrade, DarkLight will perform the update and then ask if you want to restart. If you would like to manually check, choose the menu item Help → Check for Updates.

Client/Server Updates: For installations running Client/Server, the Server will receive the update from Champion's update server and the Client will receive its update from its local server. To check for and install an update, enter p2update update in the console. If an update is available you will be prompted to install and restart.

(If you do not want the server to automatically check for updates, add dl.update=false to your ~/champion/server/champion.settings file.)

Note: Updates Don't Show Status

The time from when you agree to install the update to the time where you get the next dialog prompting to restart may be as long as 5-10 minutes. During this time, there will be no progress dialogs or prompts.

Note: The settings changed in this panel affect only the current workspace, and will take effect the next time DarkLight is launched.

Adjusting RAM Usage

DarkLight uses the Stardog database to store data and perform reasoning. By default, DarkLight assigns 2GB of RAM to the database, but if you will be processing thousands of events a day you will get much better performance by increasing this number as your system resources allow.

To change the amount of RAM the database uses, open the preferences at Window→Preferences in the Champion→Memory folders. Click on Graph Database Settings. The parameters listed in this panel are sent to Stardog when it starts up. The Xmx and Xms numbers are the amount of RAM that will be used as JVM ("heap") memory and the MaxDirectMemorySize is the amount of operating system RAM used "off-heap". For best results, change the Xmx and Xms numbers together (max: 16g), and set the MaxDirect size to something less than your total system (max: system dependent). For example, if your system has 32GB of RAM you might use -Xmx8g -Xms8g -XX:MaxDirectMemorySize=24g to allow Stardog to process more data.

A note about backups: When the backup process runs, it will temporarily create a second Stardog process that uses the same settings, so the Xmx and Xms values should be less than half of your system RAM so the backup will have enough available memory to run.

See also: Stardog Memory Usage

Backing Up Your Databases

On the off chance something bad happens to your data (power loss during a write, for example), a database backup can be used to restore lost data.

  • See also: Restoring from Backup

Each workspace saves its own backups in a config/db/backups folder. There will be one file for Working Memory and one for Contextual Memory each time the backup runs. To set when the backups run, use a Cron pattern in the top box. You can set another cron pattern to trigger when DarkLight will delete old backups. The third box lets you specify how many backups to keep. By default, backups run at 1AM 0 1 * * * and cleanup happens at 2AM 0 2 * * *. You must restart DarkLight for the changes to take effect.

  • See also: Cron Pattern Tutorial

Data Feeds View Overview

Invalid Link
The icons in the Data Feeds view show the status of data flowing through them, or show why a feed is not active. Hover over the icon for more information.

DarkLight can send e-mail on your behalf, most commonly from a Send E-Mail PRO Playbook Step or from the Summary view. Before it can send anything, it needs to be configured with your mail server's account settings.

Open the Email Notification configuration panel from the Window→Preferences menu.

  • Sender Email: The account from which the e-mail will be sent.
  • Server Name: The SMTP server that will send the e-mail on behalf of DarkLight
  • Port: The port the server uses to communicate. Typically, port 25 is used for unencrypted mail, and either 587 or 465 is used for encrypted mail.
  • Username: The username with permissions to send mail from the Sender Email
  • Password: The password that corresponds with the Username. Note that the password field will remain blank even after it is configured, but the password has been saved on the server.
  • Encrypt: If the server requires encrypted communication, turn this setting 'On'.
  • See Also: About Passwords

Once configured, click the Test Settings button and DarkLight will attempt to send a test e-mail to the sender's account. A dialog will appear with the status of the test.

TIP: Troubleshooting

If the test was unsuccessful the dialog will contain the error message to help you troubleshoot the connection.

The Monitor perspective includes a view called Log which shows messages from the DarkLight system, categorized by severity as INFO, WARN, and ERROR. An individual type can be hidden by using the triangle menu in the upper right and unchecking the mark next to it. Multiple rows can be selected by holding the Shift and Control keys while clicking. The x icon will clear the log, and the notification icon will send one or more selected rows as an e-mail. The notification feature uses the Email Notification settings.

Automatic Error Report via Email

If an error occurs, a small window will appear in the lower-right corner asking if you would like to send the error report to DarkLight Support. Multiple errors will be bundled together into one e-mail. If you choose yes, DarkLight will use the settings in Email Notification preferences. If you have not yet set that up, a dialog will take you there to fill out the settings.

The "Remember my choice" checkbox will prevent the window from opening the next time there is an error. These choices, plus the ability to change the destination e-mail address, are available from Window→Preferences in the Champion section, under Error Report.

  • help/running
  • Last modified: 2019/07/30 20:52