Manually upgrading REM to a new version

Warning This manual upgrade process is largely superseded by the partially automated upgrade process, which is now the recommended way to upgrade a Tomcat based REM installation in a production environment.

The Rhino Element Manager stores some configuration data locally.

This includes:

rem_data

Derby database storing Rhino instances, saved credentials, users, roles, and permissions

 
rhino-ems.ks

keystore containing trust certificates for Rhino instances

 
.encryption.password

file containing the password used to encrypt and decrypt the Rhino credentials stored in rem_data

You may also have:

  • REM Plugins — installed in the plugins directory

  • REM Extensions — placed in admin/extensions and installed using the admin/install-extensions.sh script

Note Plugins and extensions may store their own data in REM’s home directory. Refer to the documentation for each plugin and extension you have installed for information on what additional files need to be considered when upgrading.

The upgrade process differs slightly depending on how you run REM:

Upgrading REM in the standard distribution

To upgrade REM when running it from the standard distribution package (using the embedded Jetty web server):

1

Locate the data files mentioned above in your existing REM installation.

By default they will all be stored in the root of your existing REM installation (rhino-element-manager-<old_version>).

2

Copy the files mentioned above into the root of your new REM installation (rhino-element-manager-<new_version>).

cp -R rhino-element-manager-<old_version>/rem_data \
    rhino-element-manager-<old_version>/rhino-ems.ks \
    rhino-element-manager-<old_version>/.encryption.password \
    rhino-element-manager-<new_version>/

Your new REM installation should now contain all the same data as your previous one.

3

Depending on your installation, you may need to:

Migrating REM Extensions

If you have REM Extensions installed:

1

Verify that they are compatible with the new version of REM by referring to the documentation for each extension.

2

Copy them (or newer versions of them) to admin/extensions in your new REM installation.

cp rhino-element-manager-<old_version>/admin/extensions/*.zip \
    rhino-element-manager-<new_version>/admin/extensions/

3

Run the admin/install-extensions.sh script in your new REM installation.

The extensions will be installed into the new version of rem.war

4

Following the instructions output by the script, copy admin/target/rem.war to webapps/rem.war.

5

If any of the extensions store their own data in REM’s home directory, copy those files to the new REM installation.

cp -r rhino-element-manager-<old_version>/<extension_data> \
    rhino-element-manager-<new_version>/

Migrating REM Plugins

If you have REM Plugins installed:

1

Verify that they are compatible with the new version of REM by referring to the documentation for each plugin.

2

Copy them (or newer versions of them) to plugins in your new REM installation.

cp rhino-element-manager-<old_version>/plugins/*.jar \
    rhino-element-manager-<new_version>/plugins/

3

If any of the plugins store their own data in REM’s home directory, copy those files to the new REM installation.

cp -r rhino-element-manager-<old_version>/<plugin_data> \
    rhino-element-manager-<new_version>/

Updating the database schema

The schema for REM’s Derby database (rem_data) may require updates when upgrading between major versions of REM.

REM includes a schema update tool that can apply any required schema updates automatically. All existing data will be maintained, with some data being migrated when necessary.

To enable automatic updating of REM’s database schema:

1

Uncomment this line in REM’s startup script:

#JVM_ARGS="${JVM_ARGS} -Drem.schema.update.enabled=true"

2

Start REM (stopping it first if it was already running).

Any database schema updates found to be required will be applied.
Tip Refer to rem.log for messages regarding the update process.

Upgrading REM in Apache Tomcat

To upgrade REM when running it in Apache Tomcat:

1

Locate the data files mentioned above in your ${rem.home} directory.

If you followed the original instructions for running REM in Apache Tomcat, this will be rem_home in the root of your Tomcat installation.

cd apache-tomcat-<version>

2

Make a backup copy of the entire rem_home directory.

cp -R rem_home rem_home_OLD

3

Make a backup of your existing rem.war.

cp webapps/rem.war rem.war_OLD

4

Copy the new version of rem.war into your Apache Tomcat webapps directory.

cp /full/path/to/rhino-element-manager-<new_version>/admin/resources/rem.war webapps/rem.war

4

Copy the new version of rem-rmi.jar to bin/rem-rmi.jar in your Tomcat installation.

cp /full/path/to/rhino-element-manager-<new_version>/rem-rmi.jar bin/rem-rmi.jar

5

Review the instructions for running REM on Apache Tomcat to check if there are any additional changes or steps required.

6

Depending on your installation, you may need to:

Migrating REM Extensions

If you have REM Extensions installed:

1

Verify that they are compatible with the new version of REM by referring to the documentation for each extension.

2

Copy them (or newer versions of them) to admin/extensions in the new REM distribution package.

3

Run the admin/install-extensions.sh script in the new REM distribution package.

The extensions will be installed into the new version of rem.war

4

Following the instructions output by the script, copy admin/target/rem.war to apache-tomcat-<version>/webapps/rem.war.

Migrating REM Plugins

If you have REM Plugins installed:

1

Verify that they are compatible with the new version of REM by referring to the documentation for each plugin.

2

Replace any that require upgrading with newer versions of them (making backups of the old ones if desired).

Updating the database schema

The schema for REM’s Derby database (rem_data) may require updates when upgrading between major versions of REM.

REM includes a schema update tool that can apply any required schema updates automatically. All existing data will be maintained, with some data being migrated when necessary.

To enable automatic updating of REM’s database schema:

1

Add rem.schema.update.enabled=true to CATALINA_OPTS in bin/setenv.sh in your Apache Tomcat installation.

# Enable automatic REM database schema updates
CATALINA_OPTS="$CATALINA_OPTS -Drem.schema.update.enabled=true"

2

Start Apache Tomcat (stopping it first if it was already running).

Any database schema updates found to be required will be applied.
Tip Refer to your Tomcat logs for messages regarding the update process.
Previous page Next page