Clearspace Installation GuideThis document describes how to install Clearspace, an application for supporting communities that want to create and share content and collaborate on projects. If you haven't already, you might be interested in reading the README.html file included at the root of the Clearspace distribution. It provides a set of streamlined installation instructions in addition to listing known issues. Clearspace Distributions. Clearspace is downloadable in two distributions. For more information, see Files in the Distributions. If you're administering your Clearspace installation, be sure to check out the Clearspace Administrators' Guide. Setting up Clearspace is pretty easy through its user interface alone, but you might be interested in the information the Guide provides about what can be done (by both users and administrators) in Clearspace. 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. 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 OverviewTo complete the installation of Clearspace, you'll need to perform each of the following steps:
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 distribution), the URL will be http://localhost:8080/clearspace. After you complete the setup tool, use the admin console to begin setting up your Clearspace installation for use by the community. System RequirementsBecause Clearspace is a pure Java application, it will run on any platform where Java (JDK 1.5 or better) is installed. Clearspace requires a Java application server and a database. The following lists supported technologies and recommended system configuration.
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). Files in the DistributionsThe files in your distribution will differ depending on whether you downloaded the standalone distribution or WAR distribution. Among the things you'll find in both distributions are:
Standalone DistributionThe standalone distribution includes an application server. This 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 embedded database. If you're doing this, 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 embedded database), see Database Setup for further installation instructions. From a command prompt, use the BAT (for Windows) and SH (for Unix-based OSes) files to start and stop Clearspace on the included app server. jive_clearspace_standalone_x_x_x/ |- database/ |- jiveHome/ |- server/ |- webservices/ |- README.html |- start-clearspace.bat |- start-clearspace.sh |- stop-clearspace.bat |- stop-clearspace.sh WAR DistributionThe 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 Database SetupClearspace stores data about users, documents, spaces, and so on in a database. You can use either your own database (Clearspace supports several of the most common) or the embedded 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. Both distributions include an embedded database, but you should use a separate database for production deployment. If you're using the embedded 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. See Resin JNDI example. Note: The embedded database Clearspace provides is suitable for evaluation and testing, but you shouldn't use it for deployment. If you want to use the embedded database, simply select the "Embedded 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: MySQL 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 standalone distribution of Clearspace includes a standalone application server; if you use this server the path is for installing the JDBC driver is <installation_directory>/server/shared/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 MySQLSetup Instructions
MySQL Character Encoding IssuesMySQL 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 introduces better support for character encodings than previous versions. This new functionality will assign 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 IssuesYou 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 DriversUse the following values in the Clearspace setup tool:
OracleSetup Instructions
JDBC DriversFor 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:
SQL ServerSetup Instructions
JDBC DriverFor 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:
PostgreSQLSetup Instructions
JDBC DriverJDBC 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:
DB2Setup InstructionsYou'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.
JDBC DriversUse 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:
HSQLDBSpecial NoteClearspace bundles HSQL as its embedded database. If you choose to use the embedded database, you can configure it with the Clearspace Setup Tool. If you have a standalone installation of HSQL, follow the instructions below to connect to it. Setup InstructionsUsing the Clearspace Setup Tool, on the Datasource Setting page, choose "Embedded Database". Jive Software recommends only choosing this option if you are using Clearspace for development or for evaluation purposes. JDBC DriversBecause HSQLDB is embedded in Clearspace, so there is no need to download the JDBC driver separately. JNDIResin JNDI Example:
In this example, the database is hosted on MySQL, the database name is clearspace with a user and password of clearspace. <database>
<jndi-name>jdbc/clearspace</jndi-name>
<driver type="com.mysql.jdbc.Driver">
<url>jdbc:mysql://localhost:3306/clearspace</url>
<user>clearspace</user>
<password>clearspace</password>
</driver>
<prepared-statement-cache-size>8</prepared-statement-cache-size>
<max-connections>20</max-connections>
<max-idle-time>30s</max-idle-time>
</database>
Application Server SetupWhile 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 full deployed and running. These instructions are part of the installation process described in the ClearspaceInstallGuide. See that document for a more complete view of the installation process. Note: If you're using the application server that's included in the standalone distribution of Clearspace, you don't need this guide. The server technologies covered here include: Apache Tomcat Apache Tomcat
BEA WebLogic ServerYou can deploy Clearspace via EAR or WAR (recommended) through WebLogic's autodeploy feature or its Administration Console. Issues and WorkaroundsIssue: WebLogic and the XFire framework are not compatible out-of-the-box. Workaround: You must set your EXT_PRE_CLASSPATH to point to the XFire jar. This should not interfere with any other web applications you are hosting. On Linux
On Windows
Issue: Weblogic may not correctly find the context-root. Workaround: Unpack clearspace.war (unzip clearspace.war), then create clearspaceWEB-INF/weblogic.xml. The file should contain the following: <?xml version="1.0" encoding="ISO-8859-1"?> <weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90"> <context-root>clearspace</context-root> </weblogic-web-app> Navigate to the now-running Clearspace instance and use the Clearspace setup tool to finish setting up Clearspace. Using the default port on WebLogic, navigate to the following URL:
Caucho Resin Server
JBoss Application Server
Jetty Server
Oracle Application Server
Issues and Workarounds
Orion Application ServerNOTE: Not supported in 1.0.0, will be supported in upcoming releases.
Issues and WorkaroundsIssue: http://www.jivesoftware.com/issues/browse/CS-525 Issue: Due to bug in Orion's classloader, XFire and Orion are incompatible out of the box. The Orion development team has indicated that this problem will be resolved with version 3.0.
SAP Web Application ServerUsing the SAP Deploy Tool:
Sun GlassFish Application ServerUsing the GlassFish Admin Console: http://localhost:4848
Setting the jiveHome DirectoryThe jiveHome directory contains configuration files, logs, data (for the embedded 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.
|