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.