Upgrading CatDV

Upgrading - Before You Start

Before performing an upgrade of CatDV Server please be aware that this will overwrite the existing installation, including potentially making non- reversible changes to the database. Therefore it is vitally important that you perform a complete backup of the catdv database and the catdv installation directory – particularly the catv.properties file, before you embark on an upgrade.

Whether or not a database schema change is needed depends on the version you are upgrading from. Often a minor point release won’t require a change whereas a major version update will. However in either case, before attempting the upgrade you should always shut down the CatDV Server and make a complete backup of the ‘catdv’ database. It is not possible to roll back a schema update other than by deleting the entire database and restoring it from the backup!

Updating the server software involves replacing the files in the server installation directory, especially lib/server.jar but possibly others. Before doing so, you should make a backup copy of the installation directory (typically /usr/local/catdvServer or C:Program FilesSquare BoxCatDV Server), especially of the configuration file catdv.properties as this might get overwritten.

When upgrading it is recommended that MySQL v5.6 or above is used.

Changing Web Server

Starting with version 6.8 CatDV Server includes a built-in web server (based on embedded Tomcat). For new installation the built-in web server is the default option, and it is also recommended for most users.

If you are currently using Tomcat and you wish to switch to the embedded web server then you must follow the steps outlined below:

Important! – if you are upgrading to a new version of CatDV Server always complete the upgrade using you existing settings. So if you were using Tomcat then when you perform the upgrade stick to using Tomcat. Do not attempt to perform the switch to the internal web server until your new version of CatDV is up and running correctly.

1. Open the CatDV Server Control Panel

Click on the Setup Wizard button

Choose the Web Server tab

Click on the Built-in Web Server option in the Web Server Panel

Check that the options filled in by the wizard are correct (they should not normally need changing)

Click Apply

You will be reminded that you must uninstall or at least disable Tomcat – otherwise the built-in web server cannot start.

Click OK – the wizard will attempt to stop the currently running instance of Tomcat but you must permanently disable or uninstall it otherwise the next time you restart your server it will start up and that will prevent the built-in web server from starting

You should will be asked to Restart CatDV Server – click Yes

Wait for the server to restart

Close the wizard

You should have 4 green lights

You’re done.

Changing Database Server

CatDV supports a number of different database servers:

A built-in database engine based on H2 MySQL/MariaDB

Microsoft’s SQL Server

When you first install CatDV Server you will be asked to choose which database server technology you want to use. Starting with CatDV Server 6.8 the default choice will be the built-in database engine, but you can choose any of the available options. (If you do choose one of the other options you will need to have already installed it and have it running before you install CatDV Server.)

Migrating to Another Database Server

If at any stage you decide to switch to another database server, to make use of the better scalability of an enterprise database server such as Microsoft SQL Server, you will need to migrate your existing data to the new database server. To do this follow the steps below:

1. Make sure your chosen database server is installed and running and, where necessary that the appropriate users, permissions etc. have been created.

Run the CatDV Server Control Panel

Click on the Stop button in the CatDV Server section to shutdown CatDV Server. Wait until it stops

Select Backup Database… from the Tools menu and follow the instructions to create a complete backup of your existing CatDV database.

Click on the Setup Wizard button to open the Setup Wizard

In the Database tab select the desired database server from the Server Type drop down menu.

Confirm that the default information filled out by the wizard (hostname, port, username etc.) is correct and if so hit Apply.

You should see a message in the Status panel to the effect that the database has not been installed yet.

Click on the Install Database button and wait for the install process to complete.

You should now have a green tick in the Database tab header.

You now have a functional but empty CatDV Database.

Close the Setup Wizard

Select Migrate Data from the Tools menu

In the Source Database section of the form that pops up enter the details for the database you were previously using – the one that has all your data in it.

Click on Start Data Migration (If you didn’t complete step 3 above you will be asked to stop CatDV Server at this point)

The process will run and you should see a progress dialog.

Wait for the process to complete

Click on the Start button in the CatDV Server panel and wait for the server to restart You should now see 4 green lights indicating that server has started correctly.

You’re done!

Switching Database Servers as Part of a CatDV Server Upgrade

If you are upgrading your CatDV Server instance to a new version and you also want to switch to another database you must perform the two actions separately:

First – upgrade your existing CatDV Server installation to the new version

Then – when everything is up and running, perform the data migration as described above. Do not attempt to switch database server while you perform the server upgrade.

Automatic Server Upgrade

On Mac and Windows, upgrading the server is now performed automatically by running the installer to install the new software and then opening the CatDV Server Control Panel. The control panel will check the database schema and offer to update it as required. The steps are:

1. Perform a backup of your database

2. Stop the CatDV Server

3. Run the server installer to upgrade the CatDV Server and the Control Panel software

4. Launch the Control Panel to upgrade the database schema (if required) and update the Web Client software and other web services

5. Restart the CatDV Server

Manual Server Upgrade

If any problems occur with the automatic upgrade (for example, the database server is not running, you are using an unsupported configuration, the upgrade scripts could not be located, or you have forgotten the MySQL root password you set up previously) please correct the problem and relaunch the Control Panel.

Manual database schema upgrade

If necessary, if running under Linux for example, you may need to manually upgrade the database schema. This involves running database scripts, depending on which schema you are currently on. For example, to upgrade from 3.21 to 3.22 you may need to run

mysql -u root -p < install/mysql/update_catdv322.sql

Replace secret with the MySQL database password you set at the time of installation. (If you did not set a password then you should omit the –p option.) Please contact [email protected] for further details.

Manual update of CatDV Server software

For further explanation of the following steps please refer to the instructions for a new installation given elsewhere in this document.

1. Identify where the workgroup server software is currently installed on your server machine. For example, /usr/local/catdvServer, /Library/CatDVServer, or C:\Program Files\CatDV Server. This directory will contain files such as launchServer and java.policy, amongst others, and a lib subdirectory containing various .jar files.

2. Shut down the CatDV server. If you are using Windows, run the UnInstall.bat script to de-register the existing “CatDV Server” NT service

3. As administrator, delete or move the server installation directory to a backup location. This step is optional but is recommended in case you need to revert.

4. Use the regular installation script to install the server in a new location, answering No when it asks whether to create the CatDV database (as it already exists). Do not simply install over the top of an existing installation as the file layout may have changed slightly and old files will remain.

5. Enter your license registration code (you will need to purchase an upgrade and receive a new license code as the old licenses are no longer valid in this version). Review the other configuration settings in catdv.properties and copy any settings that you need over from the old configuration file.

6. Relaunch the CatDV Server

Manual upgrade of Web Client

Because the new Web Client web app does not contain user-modifiable files, upgrading the web app is very straightforward:

1. Shut down the Tomcat web server

2. Replace the catdv2.war in the Tomcat webapps directory with the one from install/webapp

3. Restart Tomcat

Moving to new hardware

Migrating CatDV Server to replacement server hardware

If you need to move your current CatDV Server and Database as a result of upgrading hardware then it is important to follow these recommended steps

1. Make sure your new hardware server is installed and running and, where necessary that the appropriate users, permissions etc. have been created

Run the CatDV Server Control Panel on the old hardware

Click on the Stop button in the CatDV Server section to shutdown CatDV Server. Wait until it stops

Select Backup Database… from the Tools menu and follow the instructions to create a complete backup of your existing CatDV database

On the new server hardware install the same CatDV Server version and databse provider that is running on the old hardware – follow these steps

Check you have a fully functioning CatDV Server setup on the new hardware but with an empty database

Restore database from the CatDV Server Control Panel Tools menu and navigate to the database backup created in step 4

Wait for the process to complete

Update CatDV Server Software on the new hardware to the latest release from our downloads page

Decommission old server hardware

Click on the Start button in the CatDV Server panel on the new server and wait for the server to restart

Make sure any IP configuration changes have been made to connecting CatDV Clients and Worker Nodes You should now see 4 green lights indicating that server has started correctly.

You’re done!

Switching Database Servers as Part of a CatDV Server Upgrade

If you are upgrading your CatDV Server instance to a new version and you also want to switch to another database you must perform the two actions separately:

First – upgrade your existing CatDV Server installation to the new version

Then – when everything is up and running perform the data migration as described above. Do not attempt to switch database server while you perform the server upgrade.

Further Reading

You can find lots more information to help you make the most of CatDV Server online by visiting the CatDV Tutorials section on our web site.