How-To move an on-premises, embedded Contrast UI installation to a new Linux server

Objective

It may be necessary to migrate your On-Premises Contrast Server to a new machine, perhaps to upgrade the OS version that it is running on due to company policy.  This article details the steps to accomplish that task for an "embedded" (database server not hosted independently) installation of the Contrast Server on a Linux operating system.

Process

Backup Existing Database

On the old machine, from the bin folder under the Contrast install directory (usually /opt/contrast or /usr/local/contrast), run the backup script as root (to ensure access to everything):

sudo ./backup-db.sh

If successful you should see something like this:

Backing up Schema: contrast to /opt/contrast/data/backups/db/contrast.backup.20200710123709.sql

Copy that sql file over to the new machine.  

We're now done with the old machine so everything following pertains to the new machine.

Install New Contrast Server

Run the Contrast installer file as root as documented here (don't forget any prerequisites shown for the distribution in question).

Allow the install to complete and then wait for the new server to come up - you can tell when all is good by running:

tail -f /usr/local/contrast/logs/server.log

(for example) and wait until you see this final step:

140720 12.47.30,536 INFO  (Server.java:548) Contrast TeamServer Ready - Took 103705ms

You now have a clean install with a fresh database. 

Start MySQL Independently

What we want to do next is to replace that fresh database with the one that is contained within the backup sql file.  When we do so, we want to have the MySQL server up and running but without the Contrast Server communicating with it (which would confuse everything).

We want to start MySQL with the identical environment that is used by the Contrast Server, so to do that we can find how it's running now by doing:

ps aux | grep mysqld

which will return something like:

contras+  1298  0.1 13.6 10554656 1095164 ?    Sl   12:45   0:14 /usr/local/contrast/mysql/bin/mysqld --no-defaults --performance_schema=ON --slow_query_log_file=/usr/local/contrast/data/logs/mysql-slow.log --max_allowed_packet=1024M --innodb_buffer_pool_size=8192M --datadir=/usr/local/contrast/data/db --log_error=/usr/local/contrast/data/logs/mysql_error.log --general_log_file=/usr/local/contrast/data/logs/mysql.log --collation_server=utf8_general_ci --general_log=OFF --skip_symbolic_links=YES --character_set_server=utf8 --basedir=/usr/local/contrast/mysql --default_storage_engine=InnoDB --explicit_defaults_for_timestamp=ON --sql_mode=NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER --port=13306 --log_queries_not_using_indexes=OFF --innodb_file_per_table=ON --socket=mysql.sock --log_output=FILE --long_query_time=2 --pid-file=/usr/local/contrast/data/db/MysqldResource.pid --slow_query_log=OFF --innodb_log_file_size=4096M

The contras+ at the beginning is the service account that it runs as - it's a truncated contrast_service.  We want to run the database server just like this and as the same user so the first thing we need to do is stop the Contrast Server:

sudo systemctl stop contrast-server

and then start MySQL like so (using my example above - yours is likely the same but double check before doing so):

sudo -u contrast_service /usr/local/contrast/mysql/bin/mysqld --no-defaults --performance_schema=ON --slow_query_log_file=/usr/local/contrast/data/logs/mysql-slow.log --max_allowed_packet=1024M --innodb_buffer_pool_size=8192M --datadir=/usr/local/contrast/data/db --log_error=/usr/local/contrast/data/logs/mysql_error.log --general_log_file=/usr/local/contrast/data/logs/mysql.log --collation_server=utf8_general_ci --general_log=OFF --skip_symbolic_links=YES --character_set_server=utf8 --basedir=/usr/local/contrast/mysql --default_storage_engine=InnoDB --explicit_defaults_for_timestamp=ON --sql_mode=NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER --port=13306 --log_queries_not_using_indexes=OFF --innodb_file_per_table=ON --socket=mysql.sock --log_output=FILE --long_query_time=2 --pid-file=/usr/local/contrast/data/db/MysqldResource.pid --slow_query_log=OFF --innodb_log_file_size=4096M &

Connect to the Database Server

First find the password (the commands below assume you're in the contrast install directory - likely /usr/local/contrast):

bin/edit-properties -e data/esapi/ -f data/conf/database.properties

Then connect:

mysql/bin/mysql -u contrast -p -S data/db/mysql.sock -P 13306 contrast

You should now be in the mysql command line.

Create a Clean Database

From the MySQL command line do the following:

drop database contrast;
create database contrast;
exit;

Restore the Original Database from Backup

mysql/bin/mysql -u contrast -p -S data/db/mysql.sock -P 13306 contrast < backup.sql

(where backup.sql is the sql file you created earlier on the old machine).

Stop the Database

Get the PID:

ps aux | grep mysqld

Stop the process:

sudo kill -15 <PID from above>

Start the New Server

sudo systemctl start contrast-server

and then wait for it to come up as before by tailing the server.log

When the server is up - log in and verify that all looks good.