Server Configuration

SemSpect Neo4j Server Configuration #

SemSpect comes with two deployment modes: as Graph App for usage with Neo4j Desktop and as Web App hosted by a Neo4j database server for usage with any Web browser.

This section describes the Web App mode and how to configure Neo4j in order to run the SemSpect plugin in server mode and how to set the SemSpect privileges for Neo4j users and roles.

Remark: the server mode requires a valid SemSpect server license. The server installation section describes how to deploy SemSpect in a server setting.

The SemSpect Neo4j server configuration is split over two files: the Neo4j configuration file and the SemSpect configuration file. Furthermore, the license specific settings are encoded in the SemSpect license file. The following picture provides an overview and shows how the configuration files depend on each other. Use the links in the outline on the right to jump to the details.

Your browser does not support the canvas element.

Neo4j Configuration File #

To use the integrated HTTP server of your Neo4j installation (in the same way the Neo4j Browser is exposed), the DBMS must be configured to grant access to SemSpect over the Neo4j HTTP connector.

The specific Neo4j configuration settings depend on the Neo4j version.

HTTP(S) Server Configuration #

To make SemSpect available at http://<server>:<port>/semspect/, were the port is the advertised address of the HTTP connector (same port as for Neo4j Browser, default is 7474) you need the following minimal configuration:

Important
Do not simply copy the settings below into your neo4j.conf file, but add the missing setting values to the existing ones. The only exception is dbms.jvm.additional for which you have to provide a separate entry for every parameter you want to specify.
dbms.unmanaged_extension_classes=de.derivo.semspect.server.neo4japp.server=/semspect
dbms.security.http_auth_allowlist=/,/semspect.*
dbms.unmanaged_extension_classes=de.derivo.semspect.server.neo4japp.server=/semspect
dbms.security.http_auth_whitelist=/,/semspect.*
dbms.unmanaged_extension_classes=de.derivo.semspect.server.neo4japp.server=/browser/semspect
# note that for Neo4j 3.5 the SemSpect URL is http://<server>:<port>/browser/semspect/

Initialization Configuration #

SemSpect automatically initializes when a user opens SemSpect for a particular database of a DBMS. This initialization step is required for each user/database combination and can be configured as follows.

Triggering Initialization #

SemSpect initialization can be triggered for Neo4j DBMSs of version 4.4 and later to reduce the user’s waiting time after database update.
Please refer to the SemSpect initialization for Neo4j Server project at GitHub for details on how this is done.

Multithreading for Initialization #

The number of threads used for the initialization of SemSpect at start-up and on any data change (default is the number of available processors of the host system) can be set by adding the following line:

dbms.jvm.additional=-Dde.derivo.semspect.server.init.threads=8

Note: In some environments such as docker the detection of available processors might not work correctly. In such cases the default value is 1.

Batch Size for Initialization #

The batch size used for the initialization (default is 1000) can be set by adding the following line:

dbms.jvm.additional=-Dde.derivo.semspect.server.init.batch_size=1000

SemSpect Data Folder Location #

The folder in which the SemSpect data is stored (default is semspect_data/ in the plugin folder of the Neo4j DBMS installation) can be set by adding the following line:

dbms.jvm.additional=-Dde.derivo.semspect.server.data.path=/path/to/your/semspect_data

Note: Relative path declarations are resolved relative to the plugin directory of the Neo4j DBMS.

SemSpect Configuration File Location #

The path of the SemSpect configuration (default is ./semspect_config.yaml in the plugin folder of the Neo4j DBMS installation) can be set by adding the following line:

dbms.jvm.additional=-Dde.derivo.semspect.server.configuration.path=/the_path_to/my_semspect_config.yaml

This path also specifies the location of your license file (if not otherwise specified in the SemSpect configuration file as described below).

Note: Relative path declarations are resolved relative to the plugin directory of the Neo4j DBMS.

SemSpect Server Configuration File #

The SemSpect server configuration file is optional and can be used to disable specific features globally or for particular users or roles (semspect is enabled with all features for all users per default) as well as to specify the license file location. It is a YAML file (default name: semspect_config.yaml) with the following structure:

---
version: 2                         # format of the configuration file

# optional license configuration
license:
  file: "path to semspect license" # default semspect.lic
  session-keep-alive-minutes: 15   # default 5

# optional semspect features configutation for users
settings:

  # default feature settings
  semspect: true                   # enable/disable semspect globally
  features:                        # enable/disable individual features. 
    FEATURE_KEY_1: true            # e.g. customCategories: true|false
    FEATURE_KEY_2: true

  # role feature settings
  roles:                           # overwrite 'default-settings' 
  - role: "admin"
    semspect: true
    features:
      FEATURE_KEY_1: true
      FEATURE_KEY_2: true
    
  # user feature settings    
  users:                           # overwrite roles and 'default'-settings
  - user: "neo4j"
    semspect: true
    features:
      FEATURE_KEY_1: true
      FEATURE_KEY_2: true

Settings➞semspect|features|roles|users #

The setting specification is organized according to the following schema:

settings ➞ semspect
         ➞ features ➞ [feature-key]
         ➞ roles ➞ [role-id] ➞ semspect
                             ➞ features ➞ [feature-key]
         ➞ users ➞ [user-id] ➞ semspect
                             ➞ features ➞ [feature-key]

Where role-id refers to a Neo4j role and user-id to a user of the DBMS.

Note: The general feature settings are valid for all users but are overwritten by role specific feature configurations. Users can have multiple roles. In such a case a feature is enabled if it is enabled in at least one of the users roles. Furthermore, a specific user setting overwrites the settings given in the roles of the user.

The feature-keys are the following:

  • customCategories to enable/disable the usage of SemSpect labels.
    (Reminder: The SemSpect labels are query based and will be recomputed after each modification of the graph data)
  • savedExplorations to enable/disable the storage of explorations
  • showQuery to enable/disable access to the Cypher queries of each group
  • showObjectIdInteractionsSetting to enable/disable the settings to show the Neo4j node IDs

License File Location #

To set the file name and location of your SemSpect license file (default is ./semspect.lic in the same folder as the SemSpect server configuration YAML file) use:

license ➞ file:[path to semspect license]

Note: Relative path declarations are resolved relative to the directory of the SemSpect server configuration YAML file.

Session Expiry #

The number of concurrent SemSpect users is encoded within the license file. To set the time after which the session of an inactive user is expiring (default 5) use:

license ➞ session-keep-alive-minutes:[integer]

SemSpect Configuration Validation #

To test the configuration (syntax check) after modification use the following java command from the command line in the folder where the plugin and configuration are located:

java -cp semspect_neo4j-plugin-1.3.0.jar de.derivo.semspect.server.TestConfiguration

If your configuration is located outsite the plugin folder, add the following parameter to the java command:

-Dde.derivo.semspect.server.configuration.path=/the_path_to/my_semspect_config.yaml

#e.g.
java -Dde.derivo.semspect.server.configuration.path=/tmp/my_config.yaml -cp semspect_neo4j-plugin-1.3.0.jar de.derivo.semspect.server.TestConfiguration

Reloading your Configuration #

To trigger a reloading of the configuration without restarting the DBMS use following command in Neo4j Browser:

CALL semspect.reloadConfig