Created by James Hurrell on May 03, 2022

Summary: this page provides information about how to backup your CAST Imaging instance and restore it in case of a catastrophic failure.

Introduction

Designing an appropriate backup strategy for your CAST Imaging is essential in order to protect your data from a catastrophic hardware failure. A restore operation involves performing a clean install (for Windows or for Docker) of the same version of CAST Imaging as was running prior to the failure and then restoring backed up files.

Backup process

The backup process will backup all data and configuration files that are required to return the CAST Imaging to its state at the time of the backup.

Neo4j database backup

The Neo4j database must be backed up. To do so there are two methods available:

Copying the Neo4j_data folder

Microsoft Windows via traditional installer

The database needs to be shutdown cleanly before running the backup. Browse to the neo4j\bin in your CAST Imaging installation folder, by default this is located here: %PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin and open a Powershell/CMD window in the same directory and stop the Neo4j Windows Service using the following command:

neo4j.bat stop

It can take a few seconds. Check the status to ensure it has stopped before proceeding:

neo4j.bat status

When fully shutdown, you can take a backup simply by copying the Neo4j_data folder (and all contents) to another location. By default the Neo4j_data folder is located here: %PROGRAMDATA%\CAST\ImagingSystem. You can start the service again by running the following command:

neo4j.bat start

Docker for Linux/Windows

The database needs to be shutdown cleanly before running the backup. Run the following command to stop the Neo4j container:

Docker Installer extension (ensure you are running the command from the folder created when unzipping the Docker Installer extension):
Linux: ./imaging -s stop neo4j
Microsoft Windows: imaging.exe stop neo4j

When fully shutdown, take a backup of the neo4j/data folder (and all contents) to another location. Note the locations of the neo4j data folder depending on the installer you have used:

Docker Installer extension (located in the folder created when unzipping the Docker Installer extension):
neo4j/data

You can start the container again by running the following command:

Docker Installer extension (ensure you are running the command from the folder created when unzipping the Docker Installer extension):
Linux: ./imaging -s start neo4j
Microsoft Windows: imaging.exe start neo4j

Using Neo4j's backup system - Microsoft Windows via traditional installer only

You can find out more about this in https://neo4j.com/docs/operations-manual/4.2/backup-restore/online-backup/. If using this option, CAST recommends automating this database backup, for example using a scheduled task running a batch file containing the required backup command line. Example command line:

set HEAP_SIZE=4G
"%PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin\neo4j-admin" backup --from=localhost:6362 --backup-dir=D:\backup\db --pagecache=4G
  • --from defaults to localhost:6362 therefore "localhost" assumes the backup is being run on the machine on which CAST Imaging is running. "6362" is the default listening port for backup operations.
  • --backup-dir specifies the target directory for the resulting backup. This folder must already exist.
  • --pagecache defaults to 8MB, so ensure you specify a large amount of RAM to improve performance.
  • A consistency check will be actioned by default - this is recommended, but can be disabled using --check-consistency=false.
  • The resulting backup will be stored in a folder called "neo4j" (the name of the database) in the folder defined by the --backup-dir command.

Additional configuration files backup

The following additional configuration files must be backed up:

Microsoft Windows via traditional installer:
%APPDATA%\CAST\ImagingSystem\login\application.properties
%APPDATA%\CAST\ImagingSystem\neo4j\neo4j.conf
%APPDATA%\CAST\ImagingSystem\nginx\nginx.conf
%APPDATA%\CAST\ImagingSystem\sourcecode\application.properties

Docker Installer extension (located in the folder created when unzipping the Docker Installer extension):
server\login\application.properties or login\application.properties
neo4j\neo4j.conf
nginx\nginx.conf
server\sourcecode\application.properties or sourcecode\application.properties

For example, on a Microsoft Windows installation, you could automate this as follows using a batch script and robocopy:

robocopy %APPDATA%\CAST\ImagingSystem\login D:\backup\additional_files\login application.properties /W:5 /R:10 /LOG+:D:\backup\log.txt
robocopy %APPDATA%\CAST\ImagingSystem\neo4j D:\backup\additional_files\neo4j neo4j.conf /W:5 /R:10 /LOG+:D:\backup\log.txt
robocopy %APPDATA%\CAST\ImagingSystem\nginx D:\backup\additional_files\nginx nginx.conf /W:5 /R:10 /LOG+:D:\backup\log.txt
robocopy %APPDATA%\CAST\ImagingSystem\sourcecode D:\backup\additional_files\sourcecode application.properties /W:5 /R:10 /LOG+:D:\backup\log.txt

Restore process

Clean install

The first step in the restore process is to perform a clean installation on your new target server (you do not need to perform any actions listed in the section Next Steps? - simply ensure that the installation has completed successfully). You must ensure that you install the same version of CAST Imaging as was in use prior to the catastrophic failure.

Neo4j database restore

The restore method depends on the method used to perform the backup of the database:

Copying the Neo4j_data folder

Microsoft Windows via traditional installer

The database needs to be shutdown cleanly before restoring the backup. Browse to the neo4j\bin in your CAST Imaging installation folder, by default this is located here: %PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin and open a Powershell/CMD window in the same directory and stop the Neo4j Windows Service using the following command:

neo4j.bat stop

It can take a few seconds. Check the status to ensure it has stopped before proceeding:

neo4j.bat status

When fully shutdown, delete the Neo4j_data folder from the clean installation, by default this is located here: %PROGRAMDATA%\CAST\ImagingSystem. Restore the backed up Neo4j_data folder (and all contents) to %PROGRAMDATA%\CAST\ImagingSystem. You can start the service again by running the following command:

neo4j.bat start

Docker for Linux/Windows

The database needs to be shutdown cleanly before running the backup. Run the following command to stop the Neo4j container:

Docker Installer extension (ensure you are running the command from the folder created when unzipping the Docker Installer extension):
Linux: ./imaging -s stop neo4j
Microsoft Windows: imaging.exe stop neo4j

When fully shutdown, delete the neo4j/data folder (and all contents) from the clean installation and restore the backup. Note the locations of the neo4j data folder depending on the installer you have used:

Docker Installer extension (located in the folder created when unzipping the Docker Installer extension):
neo4j/data

You can start the container again by running the following command:

Docker Installer extension (ensure you are running the command from the folder created when unzipping the Docker Installer extension):
Linux: ./imaging -s start neo4j
Microsoft Windows: imaging.exe start neo4j

Using Neo4j's backup system - Microsoft Windows via traditional installer only

If you chose to backup Neo4j using Neo4j's own backup system as documented above, you should use the restore commands below. You can find out more about this in https://neo4j.com/docs/operations-manual/4.2/backup-restore/restore-backup/. For example, the following command will restore the backed up database, overwriting the database installed during the clean installation:

"%PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin\neo4j" stop
"%PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin\neo4j-admin" restore --from=D:\backup\db --force
"%PROGRAMFILES%\CAST\ImagingSystem\neo4j\bin\neo4j" start
  • --from should point to the exact same path as defined by the command --backup-dir used in the backup process.
  • --force ensures that the existing database is overwritten with the backup.

Additional configuration files restore

Restore the following backed up additional configuration files, overwriting the files created during the clean installation:

Microsoft Windows via traditional installer:
%APPDATA%\CAST\ImagingSystem\login\application.properties
%APPDATA%\CAST\ImagingSystem\neo4j\neo4j.conf
%APPDATA%\CAST\ImagingSystem\nginx\nginx.conf
%APPDATA%\CAST\ImagingSystem\sourcecode\application.properties

Docker Installer extension (located in the folder created when unzipping the Docker Installer extension):
server\login\application.properties or login\application.properties
neo4j\neo4j.conf
nginx\nginx.conf
server\sourcecode\application.properties or sourcecode\application.properties

Restart CAST Imaging 

Finally, restart all CAST Imaging related Windows Services/Docker containers to ensure that the changes are taken into account.