Optimizing Neo4j memory allocation

Overview

Out of the box Neo4j  - the graph database system used to power the CAST Imaging results - is set to use 12GB of RAM memory (JVM heap, initial and maximum) via the following two specific settings in the neo4j.conf file:

server.memory.heap.initial_size=12G
server.memory.heap.max_size=12G

This configuration is designed to work in most situations, however, it may not be enough for your use case. In general, a sure sign that you need to modify the amount of RAM memory allocated to Neo4j is when objects fail to load in the results - particularly if there are a large number of objects to display - this is because the query used to fetch the objects for display is not completing before a timeout occurs. This timeout will manifest itself as a 504 (gateway timeout) error in the browser. Allocating additional RAM to Neo4j can help reduce the time required to complete the query.

To customise the JVM heap memory values, follow the instructions below.

Microsoft Windows

Step 1 - Edit the neo4j.conf file

Locate the following file:

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

Edit the file and update the following entries as required by your environment and then save the file:

server.memory.heap.initial_size=12G
server.memory.heap.max_size=12G

Step 2 - Run the update script

Run the following command (from a CMD window with elevated permissions (right click, Run as administrator)) to ensure that the service is updated with the new configuration:

"%PROGRAMFILES%\CAST\Imaging\CAST-Imaging-Viewer\neo4j\bin\neo4j" windows-service update

Step 3 - Restart services

Finally, restart the CAST Imaging Viewer Neo4j Graph DB Microsoft Windows service to ensure your changes are taken into account.

Linux via Docker/Podman

The Neo4j heap memory settings (server.memory.heap.initial_size and server.memory.heap.max_size) are provided “out of the box” through the equivalent NEO4J_server_memory_heap_initial__size and NEO4J_server_memory_heap_max__size options in the /opt/cast/installation/imaging-viewer/.env file (provided with CAST Imaging’s installer) - see imaging-viewer .env file. CAST recommends using the /opt/cast/installation/imaging-viewer/.env file where possible to configure initial and heap memory values.

Important: Settings in the .env file override custom settings made via other methods of updating Neo4j configuration unless the value of the equivalent parameter in the .env file is removed - see described in Customizing Neo4j for more details.

For detailed instructions on modifying the .env file, see:

• Managing .env files
• imaging-viewer .env file