Server Mode

SemSpect Web App for Neo4j Server #

This section is about the SemSpect Web App for Neo4j Server which requires a SemSpect server license. If you want to use the SemSpect Graph App in Neo4j Desktop, see these installation instructions.

This section assumes an already deployed Neo4j installation (enterprise or community edition). Please see the Neo4j Installation instructions for information on how to set up and operate Neo4j in server mode.

Installation #

  • Download the latest version of the SemSpect plugin: semspect_neo4j-plugin-8.0.0.jar
  • Copy the plugin and the license file into the ./plugin folder of the DBMS.

Configuration #

The configuration is split over two files: the (standard) Neo4j configuration file and the (optional) SemSpect configuration file.

The following picture 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 (required) #

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 server.jvm.additional (resp. dbms.jvm.additional for Neo4j v4) for which you have to provide a separate entry for every parameter you want to specify. 
server.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_allowlist=/,/semspect.*

Please also make sure that the user running Neo4j has rights to write into the plugin folder (see SemSpect Data Folder Location) and that you have placed the SemSpect plugin in this folder.

If the procedures security is active on your server, you must also allow access to the SemSpect procedures. If the access is denied you will get a “plugin not found” error even if the plugin was correctly installed. In the following example SemSpect is added to the procedures list that was restricted to the APOC procedures:

dbms.security.procedures.allowlist=apoc.*,semspect.*

Initialization Configuration (optional) #

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 (optional) #

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 (optional) #

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: 

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

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 (optional) #

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

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

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

SemSpect Data Folder Location (optional) #

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: 

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

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 (optional) #

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: 

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

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 (optional) #

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 15

# 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.

Note: The SemSpect features enabled for a given user are available for all databases to which the user has been granted access on the DBMS (directly or through one of its roles).

The feature-keys are:

  • 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 15) 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-7.0.1.jar de.derivo.semspect.server.TestConfiguration

If your configuration is located outside 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-7.0.1.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