Migrating Polarity Servers

Steps to Migrate from "Source" server to "Target" server

The following instructions walk through the steps required to migrate from an existing Polarity Server (the Source, to a new Polarity Server (the Target).

These instructions will wipe out any data currently existing on the Target server and replace it with data from the Source server.

Validate Servers are Running the Same Version

Ensure the Target server is setup and is running the exact same version of the server as the Source server. You can check the versions by running the following script on both servers and ensuring the RPM versions match:

/app/polarity-server/scripts/polarity-status.sh

In the event the versions or RPMs don't match please contact us at [email protected] for additional instructions on how to upgrade your Source server.

If the servers are the same version, continue with the below instructions.

Validate Servers are Running the Same Version of PostgreSQL

Both servers need to be running the same version of PostgreSQL to ensure the database backup file from the Source server can be applied correctly to the Target server. To check the version of PostgreSQL that is running locally, use the following command:

sudo su - postgres -c "psql -c 'SELECT version();'"

Ensure the versions on both servers match.

If your Source server is running version 9.5 of PostgreSQL we recommend upgrading to version 13 prior to doing the migration. Follow the guide below to upgrade the Source servers database to version 13. Once complete, proceed with the rest of the migration steps below.

Upgrade PostgreSQL to v13

Stop the Polarity Service on Target and Source Servers

On both the Source and Target server stop the polarityd process:

sudo systemctl stop polarityd

Backup Source Server

The next step is to backup the source server. Run the following command on the source server:

sudo su - postgres -c '/app/polarity-server/data/backups/db-backup.sh'

If you see cannot access errors related to the logs directory of integrations these errors can be safely ignored. The backup script does not copy any logs you may have from your integrations but the integrations themselves are copied.

After the backup is complete you will find a tgz file on the server located at /app/polarity-server-backups. The backup files include timestamps in the filename. Find the most recent backup file which will be the one you just created. The file will be of the format:

new-<date>.sql.tgz

Restore Backup on Target Server

Copy the backup file (new-<date>.sql.tgz) to the Target server. Once copied over you can now run the database restore script using the following command on the Target server.

sudo su - postgres -c '/app/polarity-server/data/backups/db-restore.sh \
/absolute/path/to/new-<date>.sql.tgz'

Replace new-<date>-sql.tgz with the path to your database backup copied from the Source server.

❗If you get an error that the backup file is not of the right format please ensure that the backup file is readable by the postgres user. This includes the directory the file is located in. Copying the file to /tmp will often fix these permission issues.

cp new-<date>.sql.tgz /tmp
cd /tmp
chmod a+r new-<date>.sql.tgz
sudo su - postgres -c '/app/polarity-server/data/backups/db-restore.sh \
/tmp/new-<date>.sql.tgz'

Additionally, please ensure you provide the full absolute path to the backup file (not a relative path)

When the restore process finishes you will need to copy the integrations to the correct location on the server using the command:

cp -r /app/polarity-server-backups/restore/integrations/* \
/app/polarity-server/integrations/.

Finally, ensure the integrations directory is owned by the polarityd user

chown -R polarityd:polarityd /app/polarity-server/integrations

Copy Secret Key from Source server to Target server

You will need to copy the secret key from the Source server config file to the Target server config file. Find the key by opening the config file on the Source server and looking for the property polarity.integrations.secretKey.

vi /app/polarity-server/config/config.js

Copy the property polarity.integrations.secretKey to the config.js file on the Target server and then save the config.js file.

Do not copy the entire config.js file from the Source server, just the polarity.integrations.secretKey property within the config.js file.

Refresh the User Stats Materialized View on the Target server

The next step is to regenerate the materialized view which contains user statistics information.

sudo su - postgres -c 'psql -d breach -c \
"REFRESH MATERIALIZED VIEW polarity.user_stats;"'

Flush Database Cache on Target Server

Flush the redis backed database cache on the target server to ensure that old database values are not used.

sudo /app/polarity-pg-cache/bin/redis-cli -p 9379 -n 0 flushdb

Restart the Polarity service

On both the Source and Target server you can now restart the polarityd process:

systemctl restart polarityd

To ensure all services are up and running as expected you can run the status script on the Target server using the following command:

/app/polarity-server/scripts/polarity-status.sh

Copy License File (Optional)

You may need to move your license file from the Source server to the Target server. If so, please copy the following file from the Source server and place it in the same location on the Target server. The file should be owend by the polarityd:polarityd user:

/app/polarity-server/license/polarity.lic

After copying, ensure ownership of the license is correct and restart the polarityd service:

chown -R polarityd:polarityd /app/polarity-server/license/polarity.lic 
systemctl restart polarityd