pdf

Clearspace Upgrade Guide

This document describes how to upgrade to the latest versions of Clearspace from previous versions of Clearspace.

Currently, upgrading from previous Jive Software products (Jive Forums, Integrated server) is not supported. We'll be supporting this type of migration in a future release.

Important Note
Make sure to backup your jiveHome directory and backup your database before doing an upgrade.

Steps for Upgrading the Standalone Installation

  1. Verify you've backed up your jiveHome directory and database.
  2. Backup your Clearspace_HOME/server/shared/lib directory or, alternatively, after unzipping your new Clearspace download, you will need to copy the appropriate JDBC driver into the server/shared/lib directory. In either case the JDBC driver needs to be in this directory before restarting the standalone instance.
  3. Unpack the new distribution of Clearspace.
  4. Rename the jiveHome/ directory that comes with this distribution to something other than jiveHome, you won't be using this directory (for example, mv jiveHome/ jiveHomeUnused/).
  5. Create a symbolic link inside the unpacked distribution to your permanent jiveHome:
    • UNIX/Linux/Mac: Create a symbolic link to your permanent jiveHome directory in the Clearspace directory called jiveHome (for example, ln -s /opt/jiveHome jiveHome)
    • Windows: You can also create a symbolic link to your jiveHome directory if you have Junction installed (http://www.microsoft.com/technet/sysinternals/utilities/Junction.mspx), or copy your permanent jiveHome into the Clearspace directory.
    • You will need to copy your database JDBC driver back into the server/shared/lib directory before restarting the standalone Clearspace instance
    • Issue the command start-clearspace.sh or start-clearspace.bat
  6. Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Steps for Upgrading the WAR Installation

  1. Verify you've backed up your jiveHome directory and database.
  2. Delete or move your previous WAR (and exploded WAR files) from your application server's web application directory (usually webapps/).
  3. Unpack the new distribution of Clearspace.
  4. You will need to point your Clearspace instance at your permanent jiveHome directory (which you have already backed up), this can be done in a few different ways:
    • Option 1: Use the setup tool. Use the Clearspace setup tool to set the value. After you deploy the web application you will have to run through the setup tool again, but you can point Clearspace at your current jiveHome and all your previous settings will be retained. Caution: When resetting the jiveHome location be sure that you click Continue and not Create Directory — you do not want to overwrite your jiveHome.
    • Option 2: Use the EditWAR tool. The EditWAR tool is a small application which will modify the packaged web application (clearspace.war) to point to the jiveHome directory. The clearspace.war file is also in the base directory of this distribution.
      To invoke the EditWAR tool, open a command prompt in the base directory of this distribution and execute this command:
      java -jar EditWAR.jar clearspace.war
      The tool will then lead you through the process of updating the WAR.
    • Option 3: Set a JNDI value (advanced). Set the location of the jiveHome directory via JNDI. In your app server, you can set a JNDI value of java:comp/env/jiveHome with a String value of the path to your jiveHome directory.
    • Option 4: Set with a system property (advanced). Set the location of the jiveHome directory manually by passing in a Java system property to your appserver. Set a property with the name of "jiveHome". Most app servers allow you to pass in an environment variable in the startup script. That might look like this:
      java -DjiveHome=/usr/foo/jiveHome -cp . com.myappserver.Server
  5. Copy the new clearspace.war into application server's web application directory, or redeploy the WAR using your application server's administration console.
  6. Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Steps for Upgrading the Source Build

  1. Verify you've backed up your jiveHome directory, database, and Clearspace_HOME/custom directory if you have added any of you own custom source code.
  2. Delete or move your previous WAR (and exploded WAR files) from your application server's web application directory (usually webapps/).
  3. Unpack the new distribution of Clearspace.
  4. Rebuild the Clearspace source as detailed in the Clearspace Source Build.
  5. You will need to point your Clearspace instance at your permanent jiveHome directory (the one you backed up), this can be done in a few different ways:
    • Option 1: Use the setup tool. Use the Clearspace setup tool to set the value. After you deploy the web application you will have to run through the setup tool again, but you can point Clearspace at your current jiveHome and all your previous settings will be retained. Caution: When resetting the jiveHome location be sure that you click Continue and not Create Directory as you do not want to overwrite your jiveHome.
    • Option 2: Use the EditWAR tool. The EditWAR tool is a small application which will modify the packaged web application (clearspace.war) to point to the jiveHome directory. The clearspace.war file is also in the base directory of this distribution.
      To invoke the EditWAR tool, open a command prompt in the base directory of this distribution and execute this command:
      java -jar EditWAR.jar clearspace.war
      The tool will then lead you through the process of updating the WAR.
    • Option 3: Set a JNDI value (advanced). Set the location of the jiveHome directory via JNDI. In your app server, you can set a JNDI value of java:comp/env/jiveHome with a String value of the path to your jiveHome directory.
    • Option 4: Set with a system property (advanced). Set the location of the jiveHome directory manually by passing in a Java system property to your appserver. Set a property with the name of "jiveHome". Most app servers allow you to pass in an environment variable in the startup script. That might look like this:
      java -DjiveHome=/usr/foo/jiveHome -cp . com.myappserver.Server
  6. Redeploy the new clearspace.war into application server's web application directory, or redeploy the WAR using your application server's administration console.
  7. Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Back Up Your jiveHome Directory

The jiveHome directory is the place where Clearspace stores a number of things about your environment. The database connection information is stored there as well as logs, cached attachments, your license file, and the embedded database files (if used).

You should back this up before upgrading and you should get in the practice of backing up this directory on a regular basis. The easiest way to back up the directory is to use a ZIP or TAR application or script to package the directory.

Back Up Your Database

You should back up your database on a regular basis and before upgrades. For now, the best way to manage database backups is to follow the recommendations of your DBA or the recommendations of your database software. There are a number of tools built in to various databases. Here are a few example:

  • MySQL — Use the "mysqldump" tool.
  • Postgres — Use the "pg_dump" tool.
  • Oracle — Use the "exp" program.

There are many tools for each database; try to pick one that suits your environment.

Clearspace Upgrade Philosophy

Upgrading web applications doesn't have to be hard. We've made every effort for this to be a seamless process. If you have feedback or suggestions for this process, we'd love to hear it.

In general, upgrading between revision releases will be easy (ie, 1.0.0 to 1.0.1, or 1.0.0 to 1.0.5). Upgrades between minor releases (ie, 1.0 to 1.1, or 1.0 to 1.3) might require a bit more work but we have an upgrade wizard in the application to assist.