Customizing Neo4j

Overview

CAST Imaging uses Neo4j as its graph database system for powering CAST Imaging result storage and display. This guide explains how to customize Neo4j settings through the neo4j.conf configuration file (this governs how Neo4j functions).

Microsoft Windows

Location of neo4j.conf file post installation:

%PROGRAMDATA%\CAST\Imaging\CAST-Imaging-Viewer\setup-config\neo4j

Steps to apply changes:

Edit the neo4j.conf file at the location above
Save your changes
Restart the CAST Imaging Viewer Neo4j Graph DB Windows service

Linux via Docker/Podman

Configuration methods vary depending on your installed release of CAST Imaging.

3.5.4-funcrel and later

Available in ≥ 3.5.4-funcrel

The neo4j.conf file exists only inside the Neo4j container. You therefore have three configuration options:

Option 1: Use the imaging-viewer .env file
Option 2: Expose neo4j.conf via docker-compose.override.yml
Option 3: Add parameters directly to docker-compose.override.yml

Option 1: Use the imaging-viewer .env file

Recommended for memory related settings

Use the imaging-viewer .env file. This is the simplest method for configuring the three most commonly adjusted Neo4j parameters. It can also be used pre and post installation:

NEO4J_server_memory_heap_initial__size - equivalent to server.memory.heap.initial_size
NEO4J_server_memory_heap_max__size - equivalent to server.memory.heap.max_size
NEO4J_dbms_memory_transaction_total_max - equivalent to dbms.memory.transaction.total.max

Important: Values in the .env file always take precedence over the same parameters defined via Option 2. If you want to use Option 2 for these three parameters, you must clear their values in the .env file, e.g:

# Imaging Neo4j
NEO4J_server_memory_heap_initial__size=
NEO4J_server_memory_heap_max__size=
NEO4J_dbms_memory_transaction_total_max=

Option 2: Expose neo4j.conf via docker-compose.override.yml

This method allows you to edit the neo4j.conf configuration file directly. It can only be used post installation. Steps to apply changes:

Expose the neo4j.conf file using docker-compose.override.yml for imaging-viewer(see Managing config files and Managing docker-compose.yml files)
Edit the exposed neo4j.conf file with your desired settings.
If modifying the three memory-related parameters listed in Option 1, ensure their values are cleared in the .env file
Restart the imaging-viewer containers to apply changes:

$ cd /opt/cast/installation/imaging-viewer
$ sudo docker compose up -d server

Option 3: Add parameters directly to docker-compose.override.yml

Using this method will ALWAYS override any settings made via other options described in this page.

This method is useful for adding individual parameters without exposing the entire configuration file. It can only be used post installation. Steps to apply changes:

Find the parameter you want to modify in the Neo4j Docker settings reference (use the Docker format column).
Add it to the services:neo4j:environment section of your docker-compose.override.yml, for example:

services:
    neo4j:
        environment:
            NEO4J_db_tx_log_buffer_size=100M

Restart the imaging-viewer containers to apply changes:

$ cd /opt/cast/installation/imaging-viewer
$ sudo docker compose up -d server

See Managing docker-compose.yml files for more information.

Configuration priority

When using Linux via Docker/Podman (≥ 3.5.4-funcrel), settings are applied in this order of precedence:

Highest priority: Parameters in docker-compose.override.yml environment section (Option 3)
Medium priority: Values in the imaging-viewer .env file (Option 1 - for the three memory parameters only)
Lowest priority: Settings in the exposed neo4j.conf file (Option 2)

If a parameter is defined in multiple locations, the higher priority value will be used.

Note: The .env file values only take precedence over the exposed neo4j.conf file, but will themselves be overridden by hard-coded values in docker-compose.override.yml.

3.0.x-funcrel - 3.4.x-funcrel