Getting Started Guide - GridSphere Portal v3.0

Overview

This guide provides quick-start instructions for installing the GridSphere portal. It covers the minimal steps required to install the portal. Please have a look at the Administrator Guide after installation to configure additional portal options at run-time.

Upgrading

If you are upgrading from a previous version for GridSphere, much of the setup procedure is the same as below. Make sure the previous version of GridSphere has been shut down, and then follow the instructions provided in the Portal Migration guide.

Installation and Startup

Requirements

GridSphere requires a Java Runtime Environment (JRE), version 1.5 or higher. Sun Microsystems provides a JRE available at http://java.sun.com/j2se/1.5.0/download.jsp. Ensure that you set up the environment variable JAVA_HOME and add the java binary to your PATH.

Obtaining Packages

There are three types of installation options available to you depending on your requirements:

GridSphere WAR: This provides the complete GridSphere portal available as a packaged WAR file that can be dropped into an existing Tomcat servlet container.
GridSphere Portal: This provides a distribution of GridSphere and Tomcat that is intended to include all dependencies and can be immediately launched.
GridSphere Source: This provides the GridSphere portal source code that can be instantly deployed to a new or existing Tomcat servlet container.

All GridSphere distributions can be found on the GridSphere website download page at http://www.gridsphere.org/r/download.
More information on installing each of the three distributions is provided below:

Jakarta Tomcat

Unless you are installing the GridSphere Portal distribution that comes packaged with a version of Tomcat, you will need either a new or existing Tomcat servlet container v5.5 or higher. You can find the latest Tomcat 5.5.X distribution available as binary from http://tomcat.apache.org/download-55.cgi. In addition, Tomcat provides several different packages. It is very important that you download and extract the following packages:

Core
Administration Web Application
JDK 1.4 Compatability Package (It is frequently asked why this package is necessary since GridSphere uses JDK 1.5, however, it provides xercesImpl.jar and xml-apis.jar that are needed)
Once the three above packages have been downloaded, make sure they are all extracted in the same directory.
We will assume from now on that $CATALINA_HOME refers to the directory where you have unpacked Tomcat.

You can also download a Tomcat version > 6.0.10 from http://tomcat.apache.org/download-60.cgi to be used with GridSphere.

GridSphere Source

If you are interested in installing the GridSphere source distribution, you have two options:

GridSphere versioned source archive (tarball/ZIP)
GridSphere checked out of our Subversion (SVN) repository

If you choose the versioned source archive, download the archive (tarball/ZIP) and extract it. You are now ready to build the source code.

In order to check out the source from the GridSphere repository you must have a subversion client. It is generally recommended that you use the SVN plugin provided by your IDE. When checking out GridSphere, make sure you specify the repository path as https://svn.gridsphere.org/gridsphere/trunk.

Building the Source

Building the source code requires that you have Ant installed already. Ant provides a Java based make tool and can be downloaded at http://ant.apache.org/bindownload.cgi. Make sure you set up the environment variable ANT_HOME and add the ant binary found in $ANT_HOME/bin to your PATH.

You may want to have a look at the build.properties file that provides a few configurable options allowing you to customize the URL used to access the portal (by default it is http://localhost:8080/gridsphere/gridsphere) as well as the servlet container that is used (Tomcat is the default, we are working to get it to work in Jetty):

# The following 2 params determine the URL of the gridsphere portal, default is gridsphere/gridsphere
# This is the name of the gridsphere webapp that is deployed, default is gridsphere
# An example:
#   http://<host name>/myorg/portal
#               gridsphere.deploy=myorg, gridsphere.context=portal
#
gridsphere.deploy=gridsphere
gridsphere.context=gridsphere

# possible options are jetty, tomcat
gridsphere.appserver=tomcat

Now to compile and deploy the portal into your Tomcat servlet container, simply execute the following from within your gridsphere directory:

ant deploy

You are now ready to start the portal.

(optional) Configuring host and port parameters

If you wish to change the default port (8080) used or hardcode a hostname, please edit the file $CATALINA_HOME/webapps/gridsphere/WEB-INF/CustomPortal/portal/gridsphere.properties. Normally, portal URs will be created using the hostname obtained from the servlet request. If for some reason, you need to hardcode the hostname, set the parameter gridsphere.host in the properties file. To configure the port, look for the parameter gridsphere.port.http and set it to the port you wish to use. You will also need to configure the Tomcat port in the file $CATALINA_HOME/conf/server.xml. Look for the following lines:

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector port="8080" maxHttpHeaderSize="8192"
           maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
           enableLookups="false" redirectPort="8443" acceptCount="100"
           connectionTimeout="20000" disableUploadTimeout="true" />

and change the port 8080 to the desired value.

Starting the Portal

You can start the GridSphere portal by running the startup.sh script (startup.bat for Windows users) in the $CATALINA_HOME/bin directory.

$ cd $CATALINA_HOME/bin
$ ./startup.sh
$ tail -f ../logs/catalina.out  (optional displays logging information while portal is running)
Now go to http://localhost:8080/gridsphere/gridsphere and you should see a setup page.

Running

To shutdown the GridSphere portal, use the shutdown.sh script (shutdown.bat on Windows) which is also located in the $CATALINA_HOME/bin directory. You may want to run the portal as as a service, by installing appropriate init scripts (on Unix-like systems) or by starting as a Windows service.

Setting up the Portal

After starting GridSphere, you should see the following set-up screen:

For development and testing purposes, it's easy to simply use the included hSQL database provided. Just select the first option by clicking on the "Embedded Database" option. If you are interested in configuring an external database, please consult the GridSphere Database Support documentation.

Next, you will be prompted to create an administartor account. Please supply the necessary information and click Submit.

That's it! You're now finished with the portal setup and you can login as the administrator.

Next Steps

If you encountered any errors along the way, please consult our support documentation, otherwise, please continue following the GridSphere Portal Administrator guide to finalize your portal installation and learn more about the features provided by GridSphere.