Optimizing Neo4j memory allocation

Overview

Out of the box Neo4j external link - 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 Neo4j specific settings:

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/Docker

The Neo4j heap memory settings (server.memory.heap.initial_size and server.memory.heap.max_size) are configured through the NEO4J_HEAP_SIZE option in the /opt/cast/installation/imaging-viewer/.env file (provided with CAST Imaging’s installer).

Important: Settings in the .env file always override any changes made directly to the neo4j.conf file. To modify initial and max heap memory, you must therefore use the NEO4J_HEAP_SIZE option in the .env file. For detailed instructions on modifying the .env file, see: