Tutorial to upgrade censhare Server and Service Client, the database, and the configurations.


A walk-through of the update process that enables administrators to perform an update of the censhare system by themselves.


Release information

This tutorial is only valid until censhare 2021.2.1.

As of censhare 2021.2.x:

    • To install a new censhare system or upgrade your existing system to censhare 2021.2 or above, you have to install or update to censhare WP and Keycloak.
    • There are some important changes to installation and configuration.
    • Continue here with the installation and upgrade: censhare WP

Preparation

Create backups

To be able to roll back your update during the update process, create the relevant backups first.

  • Create a backup of the database. For example with a Database Export on your Oracle Database or PostgreSQL Database

  • Create a backup of the assets in your censhare system.

  • To compare changes of configuration files with your current censhare-Server version, backup the app directory:

    cp -a ~/css/app ~/last_css_app
    CODE

Prepare Oracle database

Since censhare-Server version 2020.1.x, it is required for Oracle Databases to Enable Oracle Extended Data Types.

Update censhare - Bugfix release

For an update to a new bugfix release, just run the following command. You can do this for censhare-Server and censhare-Service-Client separately.

yum update censhare-Server censhare-Service-Client --enablerepo="censhare*"
CODE

Update censhare Server - minor/major release

Update to minor/major releases may include updating your configuration files, your assets, and the database as the RPM may update the Database Schema if necessary. So for a rollback, a backup restore may be needed.

STEP 1: Create the necessary backups to be prepared for a roll-back. For more information, see the section Preparations.

STEP 2: Retrieve the necessary repositories and change the repository URL as explained in Available Repositories.

STEP 3: Enter the following command:

yum update censhare-Server censhare-Service-Client --enablerepo="censhare*"
CODE

This will update all components.

Please see RPM Release notes for version-specific changes, such as a change in Java version or a switch of startup method to systemd.

What happens during the update process?

  1. censhare-Server will be stopped.

  2. The software will be unpacked by the RPM and overrides the current software.

  3. The work directory will be synced with changes from work-template.

  4. The script DatabaseUpdate.sh update will be executed in order to make Database Schema updates. It will log to ~corpus/work/logs/db-update-<current-date-and-time>.log.
    You can verify the Database Schema version with the following command.

    CheckJDBC.sh

    This script uses the JDBC driver to connect to the configured database and queries for typical tables in the censhare database schema. It will also query the version of the database schema like in the following example.

    Connecting to database with user 'corpus' and url: jdbc:postgresql://my-database-server:5432/corpus
Connected!SQL test successful. 
Found 20 parties.
database.version: 2020.1.0.0000
successfully done.

  5. Files that have been compiled during runtime will be removed

  6. censhare-Server will be started if it was running already when the RPM update started. If censhare Server was stopped when the RPM update started, it will remain stopped.

Update the configuration files

You have to manually update your configuration files. This is done by comparing the old with the new configuration files and updating the new configuration files accordingly. Further hints regarding important changes for this update are listed in ~/css/Changes-Update.txt. You find this file in your censhare directory after the update.

STEP 1: After the RPM has been updated and the app directory for the old version has been saved as mentioned above under Preparations, you can run the following command to get a list of configurations files that should be reviewed for changes.

{ # check for customizing changes
  echo "The following files needs to be updated: "
   cd ~/cscs/app && for i in $(find services/ config/ -type f ! -name "*save*" | sed "s/\..*\./\./g" | sed "s/-[0-9]*-[0-9]*-[0-9]//g" | sort | uniq)
  do diff -q ~/last_css_app/$i ~/css/app/$i"
  done
}
CODE

STEP 2: For the listed files, you need to open the custom configuration and the same configuration from your new version to compare and adapt changes made in the new version to your custom configuration.

To carry out this task, we recommend that you use editors that allow for split display and diffs. For example, BBedit, Atom, Sublime, or Visual Studio Code. In the example below, we use BBedit, but you are free to choose your preferred editor.

Example comparison

Example comparison in editor BBEdit for configuration of the filesystem, with the custom configuration (left) and the new default configuration (right). You can compare each part of the files and apply changes from one side to the other.