You can upgrade to this version of Clearspace with these guidelines for each distribution.

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

Sections in this Topic

Upgrading the Standalone Distribution
Upgrading the WAR Installation
Upgrading the Source Build
Migrating from One DBMS to Another
Back Up Your jiveHome Directory
Back Up Your Database
Clearspace Upgrade Philosophy
Known Issues

Upgrading the Standalone Distribution

  1. Verify you've backed up your jiveHome directory and database.
  2. Backup your CLEARSPACE_HOME/server/lib directory (or CLEARSPACE_HOME/server/shared/lib on versions prior to version 2) or, alternatively, after unzipping your new Clearspace download, you will need to copy the appropriate JDBC driver into the server/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: 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.
  6. You will need to copy your database JDBC driver back into the server/lib directory before restarting the standalone Clearspace instance
  7. Issue the command start-clearspace.sh or start-clearspace.bat

Your new version of Clearspace should be up and running using your previously configured database and customized settings.

Note: Be sure to see Evaluation Database to Oracle with Active Directory under known limitations below.

Upgrading the WAR Installation

  1. Verify you've backed up your jiveHome directory and database. (If you're using MySQL, be sure to see the note under known issues.)
  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: 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
    • 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.
  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.

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: 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
    • 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.
  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.

Migrating from One DBMS to Another

You can use the Clearspace admin console to migrate Clearspace data from one database management system to another. Clearspace supports the following DBMSs as either source or destination systems (supported versions are those that are supported for installation; see the Clearspace Installation Guide for more details):

In the admin console, go to System > Database Migration > Database Migration. The database migration tool will migrate your Clearspace instance from one database server to another. Before beginning the migration, you must:

Note: If you begin migration but don't finish, it's possible to put Clearspace into a in-between state. In this state, you'll receive an "in-progress" message even though you're no longer migrating. If this happens, you can fix it in the admin console. In the console, go to System > Management > System Properties, scroll to locate the skin.default.maintenace.enabled property, then click its delete button. After you do this you should be able to refresh your browser to view the Clearspace UI.

Note: Be sure to see Evaluation Database to Oracle with Active Directory under known limitations below.

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 evaluation 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:

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.

Known Issues

Evaluation Database to Oracle with Active Directory

If you are currently using the evaluation database and wish to upgrade from version 1.4, 1.5, or 1.6 and switch to running Oracle with Active Directory there is an extra step you must perform in order to work around an issue within Oracle.

  1. The first step is to upgrade Clearspace to 1.7. If you are currently running on the evaluation database and using Active Directory, or if you are currently running Oracle, and want to switch from Default to Active Directory for user authentication, don't change the database or authentication settings during the upgrade process. Keep everything the same and simply run through the upgrade tasks.
  2. Once you have upgraded Clearspace, stop your application server, edit <jiveHome>/jive_startup.xml, and change <setup>true</setup> to <setup>false</false>, and restart the application server.
  3. You will be forced to re-run the setup tool, but this time you can set your new database and user authentication options to use Oracle and Active Directory.

Upgrades Using MySQL Will Convert MyISAM Tables to InnoDB

In order to support transactions in version 2, MyISAM MySQL database tables will be converted to InnoDB during upgrade. The upgrade process will handle this conversion; there is no action required on your part.

Upgrade Using DB2 Might Require Reorganizing Some Tables

If you're upgrading a Clearspace instance that uses IBM DB2, some upgrade tasks might fail with the following error message:

The database table TABLE_NAME appears to be in a REORG PENDING state. In order to proceed any further you must issue a REORG TABLE command.

The only way to resolve this is to issue a REORG command. This may take some time depending on the size of the table. There are a couple of ways to do this. One way to is use the db2 command: 

REORG TABLE <schema>.<table> ALLOW READ ACCESS;

Another way is to call a stored procedure using a SQL statement: 

CALL SYSPROC.ADMIN_CMD('REORG TABLE <table>')

Clear the Tomcat work Directory After Upgrading

After you finish the upgrade process, be sure to clear the clearspace subdirectory of Tomcat work directory before starting the application and viewing the admin console. You'll likely find this subdirectory at <tomcat_root>/work/.../clearspace. If you don't clear the directory (which contains cached application components), you might see errors when you try to view application pages.

Default Code Markup is Now Plain Instead of Java

Prior to version 2, using the {code} macro without a property would result in Java-style syntax coloring. As of version 2.1, text that was enclosed in {code} tags will be rendered merely as plain monospace text, rather than with Java syntax coloring.

Version 2.1 replaces the plain text editor, which supported wiki markup, with a more full-featured rich text editor. Here's how to change code markup back to Java syntax coloring beginning with version 2.1:

  1. Begin editing the content in the new editor.
  2. Right-click the code you want to change, then click Format > Java.