Brainspace 6 to 7 Migration Guide

Recommendations

This guide serves to document the process of migrating an existing Brainspace 6.x environment to a new Brainspace 7.0 environment. This includes all administration data, datasets, and associated work product.

• Unless otherwise directed all commands should be issued as the root user.

• If possible, allow direct root login and ssh between environments.

  • If direct root login is not possible, then a different user will need to be able to ssh between environments and permissions of the /data and /localdata directories will need to be altered to provide the user access to those directories and the files therein.

  • Before running the rysnc command, try to ssh from the Brainspace 6.x host to the Brainspace 7.0 host first to ensure that SSH keys are setup that will allow the rysnc command to complete successfully.

  • If a .pem file is required to ssh between hosts, you can use the -e option with rsync to specify a .pem file, for example:

    • rsync -e "ssh -i /path/to/mykeypair.pem" …

• Ensure rsync is installed on both the 6.x and 7.0 hosts.

Step 1 – Install Brainspace 7.0

On the new machines designated to run Brainspace 7.0, perform the installation process as defined in the Brainspace 7 Installation Guide.

This can be done ahead of the time that is allocated to perform the 6.x to 7.0 migration, if you are not using an external Postgres database such as Amazon RDS. In such a case, the Postgres DB is managed by a cloud service and not running in the Brainspace environment. This is very important: If using an externally hosted Postgres database that you plan to reuse in the 7.0 environment, you must shut down the 6.x services prior to installing 7.0 in order to avoid having both environments writing to the same database, which can corrupt the database data and will render the 6.x environment unusable.

Step 2 – Migrate Dataset Data

If using an external network-attached storage device (NAS), this step is not necessary. It is assumed that the NFS server that was configured during the installation is the same NAS device that the existing 6.x environment is using.

If the application and/or analytics hosts in the 6.x environments are serving as the NFS shares for /data and /localdata, perform the steps below to copy data from the 6.x hosts to the 7.0 application host. This step can be done ahead of time, in cases where there is a large amount of data that needs to be transferred. If done ahead of time, however, an additional rsync will need to be run at the time of the migration in order to migrate any data that was added since the first rsync was performed. This additional rsync should be much faster, as it should only need to transfer the delta between the data transferred previously compared to the updated content.

On the 6.x application host, run the following commands:

rsync -arzP --omit-dir-times /data/brainspace <7.0 application host name/ip>:/data/brainspace/

rsync -arzP --omit-dir-times /localdata/brainspace/datasets/ <7.0 application host name/ip>:/localdata/brainspace/datasets/

Once the rsync is finished, it is a good idea to ensure that the files in the destination directories have the correct permissions. To do this, run the following on the 7.0 application host:

chown -R 1604:1604 /data/brainspace

chown -R 1604:1604 /localdata/brainspace

Note

If there are DAT or native files that exist on the 6.x machine outside of /data/brainspace, they will need to be rsync’ed over to the 7.0 application host and made available at the same path that they exist on the 6.x machine.

In addition, if the paths to these files are outside of /data/brainspace or made available by a file share outside of /data/brainspace, the Docker compose configuration for the brains-app service will need to be updated to add a bind mount for that other location.

For example:

brains-app:

     volumes:

        - /my/dat_files:/my/dat_files

Step 3 – Create a Dump/Backup of Postgres Data

Note

If using an externally hosted Postgres database (Amazon RDS, for example), you can skip the steps that involve dumping and restoring the Postgres data. It is assumed that during the 7.0 installation, the externally hosted Postgres DB was used to configure the 7.0 system.

Otherwise, this is the step where we need to create the dump of Postgres data from the old database so it can be loaded into the new database in a later step.

Prior to performing the Postgres dump, shut down the 6.x application services (app and analytics) to prevent new data from being added to the DB.

# find running processes

systemctl --type=service --state=running

# start shutting them down

sudo systemctl stop brainspace-platform

sudo systemctl stop brainspace-haproxy

# analytics and on-demand analytics

sudo systemctl stop brainspace-analysis

Perform a dump of the Postgres DB (Postgres needs to be running) on the 6.x database host:

PGPASSWORD=<Postgres Password> pg_dump -U brainspace -f brainspace6-db.sql brainspace

Alternatively, you can omit the password variable and enter the password interactively, or you can switch to the Postgres user prior to running the pg_dump command and you won’t need to provide a password at all.

su - postgres

pg_dump -U brainspace -f brainspace6-db.sql brainspace

Now is a good time to shut down the Postgres DB in the 6.x environment:

sudo systemctl stop postgresql-13

Step 4 - Migrate Brainspace 6 Database Dump to Brainspace 7 Database

Use the Install UI feature to migrate the dump of the Postgres database from Brainspace 6 to Brainspace 7. To do this, first transfer the “.sql” dump file that was created in the previous step to the Brainspace 7 database host (this is the application host if using the default configuration).

Next run the Install UI and select the option Migrate DB Data (Migrate Brainspace 6 Database data to 7 Database):

Warning

Performing this step will delete all the data in the database of the Brainspace 7 instance, so this should only be done during a migration from Brainspace 6.

Next enter the full path to the location of the SQL dump file that was transferred from the Brainspace 6 database:

This will load the SQL dump from Brainspace 6 to the Brainspace 7 database, clean up the data and then bring the database up to date with Brainspace 7 changes by restarting services. This may take a few seconds depending on how much data there is to restore.

When the process is finished you should see a message like this:

Other Considerations

• The license for the 7.0 instance will need to be re-uploaded after restoring the Postgres dump from the 6.x database.

• Property file modifications need to be done manually. Look at the brainspace.properties file from the 6.x system and note any modifications that are relevant to 7.0. These can be applied to the 7.0 system using the new Server Configuration UI. A few of the configuration properties are not relevant and should not be made in the 7.0 system. These include:

  • server.port=8081

  • keystore.file.name=/etc/brainspace/ssl/brainspace.pfx

  • keystore.password=<keystore password>

  • network.security=SECURE_SELFSIGNED_CERTS

• Relativity OAuth2 client needs to be updated or a new client created that points to the Brainspace 7 instance.