Contents README Changelog FTL Changelog Known Issues pdf

This document describes how to install Clearspace, a team collaboration tool that combines discussions, blogs, wiki documents and tags.

Clearspace Distributions: Clearspace is downloadable in three distributions. For more information, see Files in the Distributions.

This document includes the following sections: 

Installation Overview— A high-level view of the installation steps.

System Requirements— Describes the technologies that Clearspace needs and supports.

Files in the Distributions— A list of what's included in the distribution.

Java Setup— Setting up Java if you're using the standalone application server.

Database Setup— Setting up a database to support Clearspace.

Application Server Setup— How to set up your application server to support Clearspace.

Setting the jiveHome Directory— Finding a good location for the jiveHome directory.

Installation Overview

Here's a high level view of installing Clearspace.

  1. Review the system requirements to make sure your system supports Clearspace.
  2. Copy the Clearspace distribution (or, optionally on Windows, its installer program) to the server you'll be using. You'll find the distribution at the Jive Software web site.
  3. Decide what database technology you'll be using with Clearspace. Data about people, content, and the means for organizing them is stored in a database that you specify while using the Clearspace setup tool. You should use a separate database for a production deployment, but the Clearspace distribution includes its own database you can use for evaluation purposes.
  4. If you're not using the evaluation database, prepare your database for Clearspace.
  5. Decide what application server technology you'll be using. The installer and standalone distributions of Clearspace include an application server. If you're installing with the WAR File, set up your application server by installing the application files and JDBC driver.
  6. Deploy Clearspace using the database and application server decisions you made in the preceding steps (if you're using the installer program, it will deploy for you).
  7. Set the jiveHome directory.
  8. It is recommended that you allocate extra memory for Clearspace when starting your application server. For example, -Xmx512M
  9. This process is finished when you complete the setup tool that is displayed when you launch Clearspace for the first time.

After you finish installing Clearspace and start the server, use its web-based setup tool to establish a database connection and to set up the administrator account. Clearspace will display the setup tool the first time you navigate to Clearspace using a web browser. The URL you use will vary depending on the application server technology you're using. By default for a local installation with the included server (standalone or installer distribution), the URL will be http://localhost:8080/clearspace. You'll find more information about the setup tool in the Clearspace Administrators' Guide.

After you complete the setup tool, use the admin console to begin configuring your Clearspace installation.

System Requirements

Clearspace requires a Java application server and a database, as described in the following recommendations. The following lists supported technologies and recommended system configuration. The following table lists the platform components supported by Jive Software for Clearspace. The components are divided into three configurations indicating level of reliability, stability, and support:

Note: Be sure also to read Fine-Tuning Clearspace Performance for tips on making the most of your configuration.


 OS JDK Application Server Database AAA
Recommended Linux (2.6 Kernel) Sun Java 6 (Latest JDK 1.6) Apache Tomcat 6.0.10 (or later in 6.0.x series) Postgres 8.x LDAP or AD

Certified

Windows Server 2003 SP2

Linux (2.6 Kernel)

Solaris 10

Sun Java 6 (JDK 1.6) with latest patches

IBM Java 6 (JDK 1.6) with latest patches

Apache Tomcat 6.0.10 (or later)

BEA WebLogic Server 9.2 (Note: WLS does not support JDK 1.6)

IBM Websphere 6.1, Fixpack 15

MySQL 5.x or better

Oracle 10.x or better

Postgres 8.x or better

LDAP or AD

Supported

Windows Server 2003 SP2

Linux (2.6 Kernel)

Solaris 10

Sun Java 5 (JDK 1.5) with latest patches

IBM Java 5 (JDK 1.5) with latest patches

Apache Tomcat 5.5.x

JBoss 4.0.5, 4.2.x, or 4.3.x

Oracle Application Server OC4J 10.1.3.2.0 or better

Oracle 9.x or better

IBM DB2 v7 or better

Microsoft SQL Server 2005

LDAP or AD

Environment

Additional Recommendations

When you run a server-side application, you should also have a daily backup solution. At a minimum you should back up your database on a regular basis as well as the configuration files for Clearspace (note: those are stored in one directory).

Supported Browsers

Clearspace is supported on the following browsers (browsers on mobile devices aren't supported):

Files in the Distributions

The files in your distribution will differ depending on whether you downloaded the installer (Windows only), standalone distribution or WAR distribution. Among the things you'll find in all three distributions are:

Installer and Standalone Distribution

These include an application server. The installer distribution requires the least amount of installation effort and is a great choice for evaluating Clearspace. For the quickest installation (such as for evaluation), use the included application server and evaluation database. With the standalone distribution, included app server and evaluation database, installation is complete when you extract the distribution's contents as shown in the hierarchy below.

If you're going to be using a separate database technology (rather than the evaluation database), see Database Setup for further installation instructions.

To start Clearspace:

jive_clearspace_<dist>_x_x_x/ |- database/ |- jiveHome/ |- server/ |- webservices/ |- README.html |- start-clearspace.bat |- start-clearspace.sh |- stop-clearspace.bat |- stop-clearspace.sh

WAR Distribution

The WAR distribution does not include an application server. This distribution is intended for deployment on the application server of your choice. Clearspace supports several app server technologies as describes in the System Requirements.

The clearspace.war file is a standard Web Application Archive (WAR) that contains the Clearspace application.

jive_clearspace_war_x_x_x/ |- database/ |- jiveHome/ |- webservices/ |- clearspace.war |- EditWAR.jar |- README.html

Java Setup

Clearspace requires a valid Java installation and a JAVA_HOME environment variable set. If you already have an application server installed then you already have Java installed and working properly. You'll need to go through the following steps if you're using the standalone distribution. The installer installs Java for you.

Java Installation Instructions

You can install Java so that it will be found system-wide, or you can install it so that it will be found by the standalone distribution.

Download the Java Distribution
  1. Download the Java distribution for your OS:
Installing Java for Standalone Use
  1. Follow the installation instructions for your platform. Record the path to the directory where you installed Java.
  2. Set a JAVA_HOME environment variable. An environment variable is a way tell Clearspace where Java is installed.
    • Windows
      • On your desktop, right click on 'My Computer', select 'Properties'
      • Click the Advanced Tab
      • Click the Environment Variables button
      • Under System Variable, click New.
      • In the 'Variable name' field, enter: JAVA_HOME
      • In the 'Variable value' field, enter the path to your JDK installation (e.g. C:\Program Files\Java\jdk1.6.0).
      • Click OK on all open System Properties screens (3)
    • Unix
      • Open your favorite text editor and type the following text: export JAVA_HOME="<java_install_path>", where <java_install_path> is the directory where Java is installed. For example: export JAVA_HOME="/Library/Java/Home/".
      • Save this to a file called setJavaHome in the Clearspace standalone installation directory. For example, if you extracted Clearspace to /home/clearspace/jive_clearspace_standalone_2_0_1 then you'll save this file as /home/clearspace/jive_clearspace_standalone_2_0_1/setJavaHome.
  3. You've now completed the Java installation.
Installing Java for WAR Use
  1. Follow the installation instructions for your platform. Record the path to the directory where you installed Java.
  2. Set a JAVA_HOME environment variable. An environment variable is a way tell Clearspace where Java is installed.
    • Windows
      • On your desktop, right click on 'My Computer', select 'Properties'
      • Click the Advanced Tab
      • Click the Environment Variables button
      • Under System Variable, click New
      • In the 'Variable name' field, enter: JAVA_HOME
      • In the 'Variable value' field, enter the path to your JDK installation (e.g. C:\Program Files\Java\jdk1.6.0).
      • Click OK on all of the open System Properties screens.
      • Close any open command prompt windows. The next time you open a command prompt, the "JAVA_HOME" variable will be set correctly.
    • Unix/Linux
      • Edit the ".profile" file in your home directory (or corresponding file for your shell).
      • Set the JAVA_HOME environment variable by adding the following line to the file:
      • export JAVA_HOME=/path/to/java/directory
      • Be sure there are no spaces after the end of the directory name.
      • Do not add an extra slash after the directory name.
      • Save changes to the file and then "source" it: source .profile

Database Setup

Clearspace stores data about users, documents, spaces, and so on in a database. While the setup tool is designed to install the schema for the database you specify, these instructions are for when you might want or need to install the schema manually.

You can use either your own database (Clearspace supports several of the most common) or the evaluation database that's included with the Clearspace distribution. When you're setting up Clearspace with its setup tool, you'll be prompted for information about the data source you want to connect to — in other words, it's a good idea to make your database decision before using the Clearspace setup tool.

All three distributions include an evaluation database, but you should use a separate database for production deployment. If you're using the evaluation database, you can skip to Application Server Setup.

If you're using a separate database technology, you should set it up before you set up your application server. You will need to create a database from schema and ensure that the application server you're using includes JDBC drivers for the database. You can find schemas in the distribution's database directory. View the Database Setup to learn how to install the schemas and JDBC drivers.

JNDI Settings: The Clearspace setup tool provides a mechanism for configuring your data source connection, however, you can also configure this connection via your application server's JNDI settings.

Note: The evaluation database Clearspace provides is suitable for evaluation and testing, but you shouldn't use it for deployment. If you want to use the evaluation database, simply select the "Evaluation Database" option when running through the Clearspace setup tool. For more information on the setup tool, see the Clearspace Administrators' Guide.

This guide includes setup guidelines for the following database technologies: 

Clearspace Schemas. If you use your own database, you'll need to create a new database using the database schema appropriate to your database technology before using the Clearspace setup tool. You'll find schemas for nine database technologies in the database directory just beneath the root of the Clearspace distribution.

Required JDBC Drivers. You'll need to put a JDBC driver for your database technology in the application server's classpath. Your database's setup documentation should include information on how to install the schemas and required JDBC drivers. The installer and standalone distributions of Clearspace include a standalone application server; if you use this server the path is for installing the JDBC driver is <installation_directory>/server/lib. You'll need to restart your application server for the driver to be registered. For more information about setup instructions specific to certain application servers, see Application Server Setup.

Note: If you need to re-run the setup tool, open the jiveHome/setup.xml file, find the line  <setup>true</setup>, and change the true value to false. Restart your application server, point your browser at http://localhost:8080/clearspace

MySQL

Setup Instructions

  1. Make sure that you are using MySQL 5.x or later and the MyISAM table type (default).
  2. Create a database for the Clearspace tables using the MySQL command line tool:

    mysql> CREATE DATABASE <database_name>;

  3. Next import the schema file from the database directory of the installation:
    • Unix/Linux: mysql <database_name> < jive_clearspace_mysql.sql
    • Windows: mysql <database_name> < jive_clearspace_mysql.sql
  4. Start the Clearspace setup tool, and use the appropriate JDBC connection settings.

MySQL Character Encoding Issues

MySQL does not have proper Unicode support, which makes supporting postings in non-Western languages difficult. However, the MySQL JDBC driver has a workaround which you can enable by adding <mysql><useUnicode>true</useUnicode></mysql> to the <database> section of your jive_startup.xml file. When using this setting, you should also set the Jive character encoding to utf-8 in the Admin Console.

MySQL 4.1 introduced better support for character encodings than previous versions. This functionality assigns a default character encoding to the database and its tables and columns. It's best to set the default character encoding for your database before installing the Jive schema so that you can be sure that you will not have encoding problems in the future. After creating your database, execute the following line in the MySQL console:

ALTER DATABASE <database name> DEFAULT CHARACTER SET <character set>;

For example, if you plan on using UTF-8 in Clearspace, you should enable the JDBC driver workaround mentioned above and then execute this line in the MySQL console:

ALTER DATABASE <database name> DEFAULT CHARACTER SET utf8;

MySQL Max Attachment Size Issues

You can fix the max attachment size problem on a MySQL server by following the directions here:

http://dev.mysql.com/doc/refman/5.0/en/packet-too-large.html

The easiest way to change the MySQL server setting on Windows is to add a line to your my.ini file (you'll find this file in a location such as C:\database\mysql\5.0.19); on Linux, look for the my.cnf file instead. Add the following line after the [mysqld] section heading:

max_allowed_packet = 500M

After you add the line, restart MySQL.

JDBC Drivers

Use the following values in the Clearspace setup tool:

Oracle

Setup Instructions

  1. If you're connecting to the Oracle database via the command line using SQLPLUS, you can connect to the database to execute the commands above by doing the following:

    sqlplus system/XXXX

    where XXXX is the "system" user's password.
  2. Create a "clearspace" user or some other user who will "own" the Clearspace tables. This isn't necessary, but doing so will allow your tables to exist in a separate tablespace. Typical commands are as follows: 
    CREATE USER clearspace IDENTIFIED BY clearspace; GRANT CONNECT, RESOURCE TO clearspace;
  3. Next, import the schema from the database directory of the Clearspace installation using sqlplus (or your favorite Oracle tool such as Toad or DbVisualizer). If you have sqlplus on your PATH, you can execute the following command in the directory containing the Oracle schema. The following assumes you've set up a user account called "clearspace" with password "clearspace": 
    sqlplus clearspace/clearspace @ jive_clearspace_oracle.sql

JDBC Drivers

For most users, the best drivers for Oracle are the ones written by Oracle (which come with the database or can be downloaded from Oracle's website). Jive Software recommends using the "thin" drivers.

Please consult the Oracle documentation to decide which version of the JDBC thin driver is best for you. Typically, the drivers are in "classes12.zip" or "classes12.jar". Do not use the classes11.zip JDBC driver. If you use the ZIP file you may wish to rename the classes12.zip file to classes12.jar or oracle.jar because some application servers will not work correctly with ZIP files.

Use the following values in the Clearspace setup tool:

PostgreSQL

Setup Instructions

  1. Create a new database user using the PostgreSQL createuser utility: 
    createuser \-W
  2. Create the database using the "createdb" utility: 
    createdb \--encoding=UNICODE dbname
  3. Note, the --encoding switch is optional, but is a good idea so your database will support Unicode content.
  4. Grant the user permission to the newly created database. You'll need to locate the Postgres data directory — such as /var/lib/postgresql. Consult your Postgres installation or administrator — as this value might be different between installations.
  5. Once you locate the directory it should contain a file called pg_hba.conf.
  6. Open the file and go to the bottom of it — you should see an access control section. You'll need to edit access permissions for this database. The following is a sample entry: 
    local all all trust host all all 127.0.0.1 255.255.255.255 trust host all all your.ip.address 255.255.255.255 trust

    Note, this is a pretty open configuration. Please consult your system administrator for the best access configuration.

  7. Log in to the psql application using the user you made above: 
    psql \-U user_you_created \-W \-d dbname
  8. Once there, run the following command to import the Clearspace database schema from the database directory of the installation: 
    \i /path/to/jive/schema/file.sql
  9. Proceed to the Clearspace setup tool and use the appropriate JDBC settings when prompted.

JDBC Driver

JDBC Driver for PostgreSQL can be found in various distribution packages at PostgreSQL's Home Page. Refer to the JDBC documentation at that site for the latest driver and for more information.

Use the following values in the Clearspace setup tool:

DB2

Setup Instructions

You'll need to create a new database with a name limit of eight characters, or use an existing database. Connect to the database using any valid user name allowed to create tables and indexes. Keep in mind that DB2 UDB applies the user name as the table schema. Use the same user when you configure Clearspace with the administration interface.

  1. Using the DB2 Control Center, open Object View and expand the tree so you can view the list of databases.
    1. Right-click the "All Databases" folder, then select Create Database (either Standard or With Automatic Maintenance); follow the steps in the wizard to create your new Clearspace database.
    2. Once the database is created, single-click on the Clearspace database and verify that you are connected, if not, click the "Connect" link in the bottom window of the Control Center.
    3. Once connected, right-click on your Clearspace database and select "Query".
  2. Using the command line, execute the following: 
    DB2 CREATE DB [DBNAME] ALIAS [DBALIAS] DB2 CONNECT TO jive USER [DBUSER] USING [DBPASSWORD]
  3. Start the DB2 command window (in Windows), or the user's shell (in Unix) and import the schema (found in the database directory of the installation) with: 
    db2 \-tvf jive_clearspace_db2.sql

Default Max Attachment Size Limited to 1MB

By default, the maximum size for a BLOB in DB2 is 1MB; this limits the maximum attachment size in Clearspace to 1MB. The issue will be fixed in an upcoming release, but for now, the work around is to issue the following command against your Clearspace Database hosted by DB2. (This fix has been tested on DB2 9.1.)

ALTER TABLE jiveAttachData ALTER attachmentData SET DATA TYPE BLOB(2G)

For more details see forum thread: http://www.jivesoftware.com/jive/thread.jspa?messageID=115395 or issue tracker: http://www.jivesoftware.com/issues/browse/CS-1171

JDBC Drivers

Use the JDBC 1.2 compliant driver, db2jcc.jar and valid db2jcc_license_cu.jar, located in the bin directory of your DB2 installation directory:

<DB2_INSTALL_DIR>\SQLLIB\BIN\db2jcc.jar, db2jcc_license_cu.jar

Use the following values in the Clearspace setup tool:

SQL Server

Setup Instructions

  1. When installing SQL Server you must select "Mixed Mode" authentication.
  2. First create a user using SQL Server auth; the default database for user should be master. (Use these settings for now; you'll change them later.)
  3. Create a new Database, make the owner the user you just created.
  4. Run a new query on the database (use a select DB script if you have one), selecting your database from the drop down and selecting Execute!
  5. Go back to your user properties and set the following:
    • Server Roles: check all
    • User Mapping: db_owner and public
  6. Click Tools > Database Engine Tuning Advisor and enter the following values:
    • ServerName = HOST
    • Auth = SQL Server
    • Authentication Login = your user

JDBC Driver

For SQL Server, Jive Software recommends using the open source jTDS Driver found here: http://jtds.sourceforge.net/

Use the following values in the Clearspace setup tool:

Application Server Setup

While Clearspace is a pure Java application, the application servers on which it can be deployed vary in how they support such applications. This document describes the application server-specific steps you might need to take in order to get your Clearspace installation fully deployed and running. 

Note: If you're using the application server that's included in the installer and standalone distribution of Clearspace, you don't need this guide. 

The server technologies covered here include:

General Server Information

Headless Servers

When deploying the WAR distribution, if the server you are deploying Clearspace on is headless, you must set the Java system property java.awt.headless to "true". If you don't, certain portions of the application that use the Java AWT for generating images will not function properly.

Enable the JVM headless mode by setting the java.awt.headless flag to true, as in the following command line example:

-Djava.awt.headless=true

Apache Tomcat

  1. Place the war file in the <tomcat-install>/webapps directory.
  2. Restart Tomcat. <tomcat-install>/bin/startup.sh
  3. Navigate to the now-running Clearspace instance and use the Clearspace setup tool to finish setting up Clearspace. Using the default port on Tomcat, navigate to the following URL: http://localhost:8080/clearspace

JBoss

  1. Put the WAR in the <jboss-install>/server/deploy/ directory, or another non-default server deploy directory.
  2. If desired, remove database settings from server/deploy/. You will have a chance to define this using the Clearspace Setup Tool.
  3. JBoss 4 does not use JDK 1.5 to compile JSPs by default, 1.5 is needed for Clearspace. Edit <jboss-install>/server/default/deployjbossweb-tomcat55.sar/conf/web.xml by uncommenting the following: 
    <!-- Uncomment to use jdk1.5 features in jsp pages-->
<init-param> 
    <param-name>compilerSourceVM</param-name> 
    <param-value>1.5</param-value>
</init-param>
  4. Start the JBoss server with the following command:
    /bin/run.sh or bin\run.bat
  5. Navigate to the now-running Clearspace instance and use the Clearspace setup tool to finish setting up Clearspace. Using the default port on JBoss, navigate to the following URL:http://localhost:8080/clearspace

BEA WebLogic Server

  1. You can deploy Clearspace through WebLogic's Administration Console.
  2. Before deploying, unzip the Clearspace WAR to a directory: unzip -d clearspace clearspace.war
  3. Deploy and start the Clearspace instance as you would any web application.
  4. Navigate to the now-running Clearspace instance and use the Clearspace setup tool to finish setting up Clearspace. Using the default port on WebLogic: http://localhost:7001/clearspace

Issues and Workarounds

Issue: WebLogic is incompatible with certain Clearspace libraries out-of-the-box.

Workaround: Use JDK 1.5 and update the EXT_PRE_CLASSPATH with the JAR files described below. (Note: WebLogic Server does not support JDK 1.6.)

  1. Configure a WebLogic domain to use the Sun or JRockit JDK 1.5.
  2. Delete weblogic.xml from exploded Clearspace WAR file. You'll find the file in the clearspace/WEB-INF directory.
  3. Set your EXT_PRE_CLASSPATH to point to the following five JAR files. The first four are included in the Clearspace WAR file, in the application WEB-INF/lib directory. Explode the WAR, then copy the fifth into the application WEB-INF/lib directory.
    • commons-logging.jar
    • wss4j.jar
    • xmlsec-1.4.1.jar
    • geronimo-ws-metadata.jar
    • velocity-tools.jar — Download from http://velocity.apache.org/download.cgi and copy into the WEB-INF/lib directory.

      You can update the path with a command such as the following:

      export EXT_PRE_CLASSPATH="/path/to/commons-logging.jar:/path/to/wss4j.jar:/path/to/xmlsec-1.4.1.jar:/path/to/geronimo-ws-metadata.jar:/path/to/velocity-tools.jar

IBM WebSphere Application Server

Note: WebSphere 6.1.0.15 or better is required for Rich Text Editor icon support.

Deploy the clearspace.war as a new application via the WAS administration console.

  1. In the administrative console, select Applications > Install New Application.
  2. Specify the location of the WAR file.
  3. On the first page of the installation process, set the context root with a forward slash, e.g. /clearspace
  4. Select to show all installation options and parameters.
  5. Leave the defaults as they are or make settings as you normally would.
  6. Among the options, choose to pre-compile JavaServer Pages files. Click Next to continue.
  7. When prompted to provide options to compile JSPs, change the JDK source level from "13" to "15".
  8. Finish and Save.

Issues and Workarounds

Issue: WebSphere is incompatible with certain Clearspace libraries out-of-the-box.

Workaround:

  1. Add aspectjrt.jar to WebSphere's libraries and add the velocity-tools JAR to Clearspace libraries. To add the aspectjrt.jar to WebSphere libraries, you can do it one of two ways, depending on whether you have access to WebSphere's lib directory on your server's file system
  2. Set a custom property.
  3. Add the Apache Velocity tools.
If you have access to the WebSphere lib directory on your server's file system

Locate aspectjrt.jar in the exploded instance of Clearspace (in its WEB-INF/lib directory). Copy the JAR in place of WebSphere's /lib/aspectjrt.jar. You'll also need the Apache Velocity tools. Download velocity-tools JAR from the Tools section of http://velocity.apache.org/download.cgi#Tools and copy it into the Clearspace WEB-INF/lib directory.

If you will be using the WebSphere administrative console

Create a shared library with the aspectjrt.jar file included with Clearspace.

  1. In the administrative console's topology tree, select Environment > Shared Libraries.
  2. On the Shared Libraries page, specify a scope that will include Clearspace, then click Apply.
  3. Click New.
  4. Specify a name and give the classpath to aspectjrt.jar, then click OK.
  5. Save the configuration.

Associate a shared library with an application server:

  1. In the administrative console's topology tree, select Servers > Application Servers.
  2. On the Application Servers page, click the name of the server to which you want to add a shared library.
  3. On the application server's detail page, click Classloader.
  4. On the Classloader page, click New.
  5. Select the Classloader mode and click OK.
  6. On the Classloader page, click the classloader that you created. If this is the first classloader that you create for your application server, it is named classloader_1.
  7. On the classloader's detail page, click Libraries.
  8. On the Libraries page, click Add.
  9. Select the shared library that you want to associate with your application server, then click OK.
  10. Save the configuration.

Create a new classloader

  1. On the page for the application server that will be deploying Clearspace, select Java and Process Management > Class loader, then click New.
  2. For class loader order, select Classes loaded with application class loader first, then click OK.
  3. Save the configuration.
  4. Click the ID for the class loader you created.
  5. Click Shared library references, then click Add.
  6. Choose the Aspectjrt library.
  7. Save the configuration.
Required after adding the needed libraries: Set a custom property and install Clearspace

Set a custom property.

  1. In the administrative console click Servers > Application Servers > server_name > Web Container settings > Web Container.
  2. Under Additional Properties select Custom Properties.
  3. On the Custom Properties page, click New.
  4. On the settings page, enter "com.ibm.ws.webcontainer.invokefilterscompatibility" in the Name field and "true" as the value.
  5. Click Apply or OK.
  6. Click Save on the console task bar to save your configuration changes.
  7. Restart the server.

Add the Apache Velocity tools.

  1. Download velocity-tools JAR from the Tools section of http://velocity.apache.org/download.cgi#Tools and copy it into the Clearspace WEB-INF/lib directory.
  2. Restart the server.

Oracle Application Server

  1. Use the instructions below to deploy the Clearspace WAR file.
  2. Navigate to the now-running Clearspace instance and use the Clearspace setup tool to finish setting up Clearspace. Using the default port: http://localhost:7777/clearspace
Remove Conflicting JAX-WS Interfaces

OC4J contains a version of the JAX-WS libraries that conflict with Clearspace. For Clearspace to deploy properly, a few rather intrusive changes must be made to OC4J to remove their JWX-WS libraries from loading.

  1. Backup <OC4J_HOME>/j2ee/home/oc4j.jar to a safe place.
  2. Extract <OC4J_HOME>/j2ee/home/oc4j.jar to temporary directory. 
    mkdir /tmp/oc4j cd /tmp/oc4j jar xvf oc4j.jar
  3. Using a text editor modify the file META-INF/boot.xml and comment out the following line: 
    <code-source path="${oracle.home}/webservices/lib/jws-api.jar" if="java.specification.version == /1\.[5-6]/"/>
  4. Repackage the JAR file, overwriting the existing file: 
    jar cvfm <OC4J_HOME>/j2ee/home/oc4j.jar META-INF/MANIFEST.MF *

References

http://www.jivesoftware.com/builds/docs/clearspace/latest/ClearspaceInstallGuide .html#ClearspaceInstallGuide-OracleApplicationServer

http://cwiki.apache.org/CXF20DOC/appserverguide.html#AppServerGuide-OC4J

Upgrade Oracle JDBC Driver (If You Are Using an Oracle Database)

The Oracle JDBC driver packaged with Clearspace is older than Clearspace requires. Confirm that you have the 10.2 or newer JDBC driver. You can download the newer driver from http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc_10201. html

If the driver is not updated there will be startup errors, and database behavior may not be as desired.

  1. In OC4J enterprise manager, click the Administration tab.
  2. Click the "Shared Libraries" link.
  3. Click the "Create" button.
  4. Enter the following information and click "Next."
    • Shared Library Name: new.oracle.jdbc
    • Shared Library Version: 10.2
  5. On the "Add Archives" page click "add."
  6. Browse for the Oracle JDBC driver JAR downloaded on your local machine, and click "Continue."
  7. Click "Next" on the next two screens to finish the add shared library process.

When deploying the Clearspace WAR file, this library should be configured in the classpath settings for the deployment descriptor. The next section will explain how to do this.

Reference

http://www.jivesoftware.com/issues/browse/CS-2730

Deploying Clearspace WAR File with a Customized Deployment Plan

The Clearspace WAR file will not deploy correctly with the default deployment plan for OC4J due to some conflicts with libraries inherited from Oracle. The deployment plan classpath must be customized to allow the WAR file to deploy.

  1. Under the "Applications" section of OC4J enterprise manager click deploy.
  2. Under "Archive is already present on the server...", specify the location of Clearspace WAR file, leave the option "Automatically create new deployment plan," and click "Next."
  3. Fill out the application attributes as below (customize the name and context to suit your needs), then click "Next."
    • Application Name: Clearspace 2.0
    • Parent Application: defaul
    • Bind Web Module to Site: default-web-site
  4. On the "Deployment settings" page click the "Configure Classloading" link.
  5. Uncheck the "Inherit parent application's shared library imports" check box.
  6. Click import next to required libraries such as your JDBC driver, or the new.oracle.jdbc library descrribed in the previous section. Finally, click "OK."
  7. Click "Deploy."

References

http://www.jivesoftware.com/issues/browse/CS-2944

http://www.jivesoftware.com/community/thread/26035?tstart=0

Setting the jiveHome Directory

The jiveHome directory contains configuration files, logs, data (for the evaluation database) and other items that Clearspace needs to run correctly. You need to set up your jiveHome directory in a permanent location. The directory must be readable and writable by your application server, but should not be in the document path of your webserver (such that someone could access the directory from a URL such as http://www.yourserver.com/jiveHome). Windows users might pick a directory such as c:\jiveHome while Unix users might install jiveHome to /opt/jiveHome.

Now that your jiveHome directory is set up, Clearspace will need to know its location. There are several ways to do this. Choosing one of the following options depends largely on how you want to register your value in your environment.