GridSphere User's Guide

The GridSphere User's Guide describes how to install and configure GridSphere. For more information on developing and packaging portlets, please consult the GridSphere PortletReference Guide and the GridSphere Tutorials. The current implementation is based upon the GridSphere Technical Design Document. The GridSphere portal framework comes in both source and binary forms. Binaries can be created from the source code and in both cases, the build environment is generally the same. The GridSphere source code comes with a README file explaining how to build the binary distribution. Both source and binaries come packaged with all the necessary third party libraries and requires a GridSphere compatible servlet container, currently Tomcat 4.1+ and Tomcat 5 are supported

You should download the latest source code release of GridSphere at http://www.gridsphere/gridsphere/gridsphere?cid=download and unzip/tar it.

GridSphere uses many quality open source libraries listed below for completeness: It is not recommended to replace the bundled libaries.

In order to build the source distribution or deploy GridSphere to a Tomcat servlet container, you will need to download Jakarta Ant. Ant is also used to run the unit tests.

The Jakarta Tomcat servlet container is required to provide a hosting environment for the GridSphere framework. Make sure you install both Tomcat and GridSphere with normal user permissions or consider creating a special portal user and installing under the portal user id.

Before deploying GridSphere to a servlet container, various configuration settings can be adjusted to customize layout, database configuration, portlet services and the portlet web applications that are started at run time. Below is a description of the various configuration files and how they are used.

As explained in the INSTALL file, GridSphere relies on Ant for its compilation and deployment. The build script, build.xml provides various targets for compiling, deploying, building javadoc api documentation, creating new portlet projects.

From inside the GridSphere source directory, you should be able to issue:

ant install

gridsphere.appserver=tomcat
            

gridsphere.appserver=jetty
            

To update to a recent version of GridSphere, you should first make a backup of your existing GridSphere configuration. To do this backup your $CATALINA_HOME/webapps/gridsphere/WEB-INF/CustomPortal directory. After downloading and installing the newer version of GridSphere using

ant install

ant update-database

GridSphere uses the Log4J logging framework and logs all messages to $CATALINA_HOME/logs/catalina.out and to $CATALINA_HOME/logs/localhost_gridsphere_log.{yyyy-mm-dd}.txt If you encounter any errors, please look at the log files for more information. In addition, the logging level can be selectively controlled by configuring the log4j.properties located in the config directory of the GridSphere source directory and then re-deploying.

By default, the portal is configured as http://localhost:8080/gridsphere/gridsphere. It is possible to change the context by editing the deployed context. Under Tomcat 4, the context file is located in $CATALINA_HOME/webapps/gridsphere-context.xml. Under Tomcat 5, the context file is located in $CATALINA_HOME/conf/Catalina/localhost/gridsphere.xml Change the following:

            <Context path="/gridsphere" docBase="gridsphere" debug="0" reloadable="false" crossContext="true">
            <Logger className="org.apache.catalina.logger.FileLogger"
           prefix="localhost_gridsphere_log." suffix=".txt" timestamp="true"/>
            </Context>
        

to

            <Context path="/myorg" docBase="myorg" debug="0" reloadable="false" crossContext="true">
            <Logger className="org.apache.catalina.logger.FileLogger"
           prefix="localhost_gridsphere_log." suffix=".txt" timestamp="true"/>
            </Context>
        

Where the context path element corresponds to your desired context.

	Important
	First move the file gridsphere.xml over to myorg.xml (or whatever name you specified in the context path)

	Important
	Second move the gridsphere webapp to myorg i.e. $CATALINA_HOME/webapps/gridsphere should be moved to $CATALINA_HOME/webapps/myorg

	Important
	Third move the $CATALINA_HOME/webapps/myorg/WEB-INF/CustomPortal/portlet/gridsphere.1 file to $CATALINA_HOME/webapps/myorg/WEB-INF/CustomPortal/portlet/myorg.1

	Important
	Finally if you are using the local hsqldb you must edit $CATALINA_HOME/webapps/myorg/WEB-INF/CustomPortal/database/hibernate.properties to use myorg and not gridsphere in the hibernate.connection.url

Now change the servlet mapping by editing $CATALINA_HOME/webapps/gridsphere/WEB-INF/web.xml

            <servlet-mapping>
            <servlet-name>gridsphere</servlet-name>
            <url-pattern>/gridsphere/*</url-pattern>
            </servlet-mapping>
        

to

            <servlet-mapping>
            <servlet-name>gridsphere</servlet-name>
            <url-pattern>/start/*</url-pattern>
            </servlet-mapping>
        

All custom settings including the default database are contained in $CATALINA_HOME/webapps/gridsphere/WEB-INF/CustomPortal. To deploy a new portal configured with the earlier customizations, simply manually copy over this directory to the new portal directory. In order for the database to work, you will have to hand edit the $CATALINA_HOME/webapps/gridsphere/WEB-INF/CustomPortal/database/hibernate.properties hibernate.connection.url entry to match the new Tomcat location.

If you want to install GridSphere behind Apache httpd2 please read the following section. Download httpd2 from http://httpd.apache.org/download.cgi.

tar xzvf httpd-2.0.49.tar.gz
cd httpd-2.0.49
./configure --prefix=/usr/local/apps/httpd-2.0.49 --enable-ssl --with-ssl=/usr/local/apps/openssl-0.9.7d --enable-so
make
make install
            

	Important
	Make sure you have at least openssl 0.9.6e installed it is needed by httpd2.

tar xzvf  jakarta-tomcat-connectors-jk-1.2.5-src.tar.gz
cd  jakarta-tomcat-connectors-jk-1.2.5-src/
./configure --with-apache=/usr/local/apps/httpd-2.0.49 --with-java=/usr/local/packages/java
make
cp apache-2.0/mod_jk.so /usr/local/apps/httpd-2.0.49/modules/
        

worker.list=gridsphere

worker.gridsphere.type=ajp13
worker.gridsphere.host=localhost
worker.gridsphere.port=8009
        

            

LoadModule jk_module modules/mod_jk.so
<IfModule mod_jk.c>
        JkWorkersFile /usr/local/apps/httpd-2.0.49/conf/workers2.properties
</IfModule>
...
NameVirtualHost YOURIP:80
...
<VirtualHost www.YOURHOST.com:80>
    ServerAdmin webmaster@YOURHOST.com
    DocumentRoot /var/html
    ServerName www.YOURHOST.com
    ErrorLog /logs/error_log
    CustomLog /logs/access_log common
    JkMount /* gridsphere
</VirtualHost>

<VirtualHost www.YOURHOST.com:443>
   ServerAdmin webmaster@YOURHOSTS.com
   DocumentRoot /var/html
   ServerName www.YOURHOST.com
   JkMount /* gridsphere
   SSLEngine on
   SSLCertificateFile    /etc/ssl/server.crt
   SSLCertificateKeyFile /etc/ssl/server.pem
   ErrorLog /logs/error_ssl_log
   CustomLog /logs/access_ssl_log common
</VirtualHost>

            
        

	Important
	These are just sample configurations. Please change them to reflect your local installation.

Please read the GridSphere Administrator's and Reference Guides for information on administering and configuring the GridSphere portal.