by Alka Gupta
May 2004
Overview ReadMe for Windows Download
Copyright 2004 Sun Microsystems, Inc. ALL RIGHTS RESERVED. Use
of this software is authorized pursuant to the terms of the license found
at http://developers.sun.com/berkeley_license.html.
Installation Instructions for Solaris or Linux
Contents
Overview
GC Portal is a Java 2 platform, Enterprise Edition (J2EE) application
available as a J2EE WAR module which can run on any J2EE Application Server.
The instructions included here specify the steps and requirements to install
and run the GC Portal on Sun Java System Application Server 7 and the
Solaris Operating Environment or 9 or Red Hat Linux 7.2 or higher.
Requirements
- Sun Java System Application Server 7.0
- Netscape browser 6.0 or above
- Solaris 8 or Solaris 9 Operating Environment or Red Hat Linux 7.2 or higher or JDS (Java Desktop System)
Installing and Running the GC Portal
Step 1. Download the GC Portal software
Download the zip archive containing the GC Portal software, called gcPortal.zip.
Step 2. Extract the GC Portal software from the archive
Extract the gcportal software from the gcPortal.zip archive.
This gcPortal.zip archive contains 4 files
sqlTables.sql
SQL scripts needed to create the Database Tables for use by GC Portal- >
gcPortal.war
Web Archive needed to Deploy GC Portal on Sun Java System Application Server 7.0
ReadMe_Solaris_Linux
Instructions for installing GC Portal on Solaris or LinuxReadMe_Windows file
Instructions for installing GC Portal on Windows
Step 3. Install and configure the Sun Java System Application Server 7.0
Download the Sun Java System Application Server 7.0. Follow the associated documentation to install and run the server. The GC Portal configuration instructions below assume that the Sun Java System Application Server 7.0 PE evaluation edition is used, which uses a flat file structure for installation. If the SE edition is used, the instructions assume that it is installed in a single directory.
Before starting and running the Sun Java System Application Server, do the following:
- Go to the
Sun_One_App_Server_HOME/domains/domain$/server$/config
directory
- Modify the
server.policy file, adding execute permission
for all files
To do this, modify the following line in this file:
// Basic set of required permissions granted to all remaining code
permission java.io.FilePermission "<<ALL
FILES>>", "read,write";
to read as follows:
permission java.io.FilePermission "<<ALL
FILES>>", "read,write,execute";
Sun_One_App_Server_HOME is the home directory of Sun Java System
Application Server ; for example, /sun/appserver7/
Step 4. Set up the GC Portal database
GC Portal can be configured to work with any database if the appropriate
JDBC drivers are available. The steps here describe how to configure it with
Pointbase, the default database bundled with Sun Java System Application
Server .
- Start the PointBase Database server that comes with Sun Java System
Application Server 7.0.
Run the following command:
Sun_One_App_Server_HOME/pointbase/server/StartServer.sh
- Start the PointBase Console
Run the following command:
Sun_One_App_Server_HOME/pointbase/client_tools/PB_console.sh
- In the Console window, type the following in the URL field
jdbc:pointbase://localhost/gcportal,new (Don't forget the
new at the end)
Leave the username and password as PBPUBLIC and PBPUBLIC
This will create a new database instance called gcportal
Note: for detailed documentation on how to use PointBase Database, refer
to the documentation in the Sun_One_App_Server_HOME/pointbase/docs
directory.
- After successfully creating the gcportal database, it says "OK Connected
to Database
jdbc:pointbase://localhost/gcportal"
- To populate the tables, Click on 'File' on the Top Menu in the Console
window, then select 'open'. Open the file
sqlTables.sql file
from the location where it is located on the system after untar'ing gcPortal.tar
- In the console window, Click 'Edit' on the Top Menu in the console window,
Select 'Select All' (also CTRL+A).
- In the console window, Click 'SQL' on the Top Menu in the console window,
Select 'Execute All'. This will create all the Tables needed by the GC Portal.
GC Portal can be configured to work with any database, including Oracle, MySQL, or others, if the appropriate JDBC drivers are available. The steps here describe how to configure the database.
To configure the new Database, open the browser window and type http://machinename:port/gcPortal/dbadmin.html
after deploying GC Portal (that is, after completing Step 9 of the installation instructions). Fill in the appropriate values for Database Driver Class, Database Connect String, Database user name and Database user password. In the GCPortal User Password field type 'dbadmin', which is the default password for administering
GC Portal by a user with GC Portal administration priveliges. The GCPortal user 'dbadmin' with password 'dbadmin' is already created by the sqlTables.sql script. Only user 'dbadmin' can modify the GCPortal DB settings. After the
Database is configured with these values, it is recommended that the admin user login to GCPortal as user 'dbadmin', password 'dbadmin' and change the 'dbadmin' user password by clicking on the 'Modify Profile' link
on the left hand side of the Home page.
Step 5. Start the Sun Java System Application Server 7
Run the following command:
Sun_One_App_Server_HOME/bin/asadmin start-appserv
Step 6. Deploy gcPortal.war on Sun Java System Application
Server
Run the following command:
Sun_One_App_Server_HOME/bin/asadmin deploy --user admin_user
--password admin_password --host localhost --port 4848
--type web --contextroot
gcPortal gcPortal.war
For help, type, Sun_One_App_Server_HOME/bin/asadmin deploy
help
Alternately, use the Sun Java System Application Server 's Administration
console.
Step 7. Configure the GC Portal
The gcPortal.war file deploys GC Portal in the following directory
Sun_One_App_Server_HOME/domains/domain$/
server$/applications/j2ee-modules/gcPortal_$
The GC Portal software is organized in the following directory structure:
- The gcPortal root directory contains all the JSPs and
HTML files
- The gcPortal/images directory contains gifs and other images
- The gcPortal/WEB-INF contains three sub-directories
- lib directory contains all the jar libraries used by the
Portal
- classes directory contains all the class files
- src directory contains all the java source files
- The gcPortal/cache directory contains the charts(graphs)
that are generated by the Portal
- The gcPortal/ scripts directory contains all the perl and awk
scripts for parsing the verbose:gc log files
- The gcPortal/CaseStudies directory contains the CaseStudies
pages and other images
- gcPortal/gclogs directory contains all the verbose:gc
log files that users upload. It creates a directory for each user by
the username in this directory, a project sub-directory for each user
project by the project name within the username directory and stores
the raw log files for a given user and project in that project sub-directory.
- The gcPortal/jvmstat1.1 directory contains the jvmstat1.1 needed for running VisualGC 1.1 and associated documentation.
- The gcPortal/jvmstat2.0 directory contains the jvmstat2.0 needed for running VisualGC 1.2 and associated documentation.
- The gcPortal/visualGCSample directory contains the jnlp files and classes needed to launch VisualGC from a browser using Java Web Start.
Before running GC Portal, 'write' permissions for the following
directories need to be set:
cd Sun_One_App_Server_HOME/domains/domain$/
server$/applications/j2ee-modules/gcPortal_$
- cache directory where the charts (graphs) are generated
chmod -R 777 cache
- gclogs directory where all the log files are stored.
chmod -R 777 gclogs
- scripts directory
chmod -R +x scripts
- WEB-INF/lib directory where Properties.txt file is written by the Portal.
chmod -R 777 WEB-INF/lib
Note: The Properties.txt file located in WEB-INF/lib
stores values for some the properties used by the Portal. When GC Portal
is run for the first time, this file is automatically generated.
To modify any default values used by the Portal, edit the respective
entries in the Properties.txt file. These default values might include:
Database DRIVER (default is com.pointbase.jdbc.jdbcUniversalDriver),
Database Connect String (default is jdbc:pointbase://localhost/gcportal),
Database username and Password (default is PBPUBLIC, PBPUBLIC),
User GC log files location (default is ../gcPortal_$/gclogs/)
Parameters EMAIL_FROM_ADDRESS and EMAIL_HOST used by the Portal.
Step 8. Download the third party software used by GC Portal
for charting graphs
- Go to http://www.ve.com/servlet.html
- Download KavaChart 4.0.1 server beans in tar/gzip format from KavaChart
Downloads.
- Untar the downloaded binary to a temporary directory. It will create
3 directories; jsp, asp and javachart.
- Go to the sub-directory named jsp. It has a file called kavachart.war
- Run the command
jar xvf kavachart.war.
It will create a directory WEB-INF.
- Copy the kcServlet.jar file from Kavachart's WEB-INF/lib directory to
Sun_One_App_Server_HOME/domains/domain$/server$/ applications/j2ee-modules/gcPortal_$/lib
Step 9. Run the GC Portal
- Type http://machinename/gcPortal
- If the server is running and GC Portal deployed, you will be taken to
the home page of GC Portal. To create a New User, Click the 'New User?
Sign in Here?' link on the page and create a new user and login. If the
database is created properly, this should successfully create a new user.
Login with the username and password just created.
Troubleshooting Tips
- If the graphs within the GC Portal do not display, make sure to set the command '
xhost +' on the machine.
If the Application Server was installed as root, try
running the command /usr/openwin/bin/xterm as
root.
If the error displayed is '/usr/openwin/bin/xterm
Xt error: Can't open display:' , then the following
steps need to be followed.
- Login as normal user
- Execute
'xhost +' command on the shell.
The following message should be displayed after the command is run:
access control disabled, clients can connect from any host
- Su or login as root
- Export DISPLAY=machinename:0.0. After that, to check if DISPLAY is set correctly,
type xterm or
/usr/openwin/bin/xterm and a xterm window should pop up.
- Restart the Application Server.
- If there are 'domain creation failed' errors while installing Sun Java System Application Server 7.0 on Red Hat Linux 9 or higher, follow the workaround given here:
http://developer.java.sun.com/developer/bugParade/bugs/4862994.html
- If there are problems in installing Sun Java System Application Server 7.0 on JDS (Java Desktop System ), look at the installation logs in /var/tmp directory, for the following errors:
Installing RPM: imq-3.0.1-0
var/tmp/rpm-tmp.55721: line 14: cd: /etc/rc0.d: No such file or directory
/bin/ln: `K15imq': File exists
var/tmp/rpm-tmp.55721: line 19: cd: /etc/rc1.d:No such file or directory
/bin/ln: `K15imq': File exists
var/tmp/rpm-tmp.55721: line 24: cd: /etc/rc3.d:No such file or directory
/bin/ln: `S52imq': File exists
var/tmp/rpm-tmp.55721: line 29: cd: /etc/rc5.d:No such file or directory
/bin/ln: `S52imq': File exists
var/tmp/rpm-tmp.55721: line 34: cd: /etc/rc6.d:No such file or directory
/bin/ln: `K15imq': File exists
execution of imq-3.0.1-01 script failed, exit status 1
Error: RPM imq-3.0.1-01 install failed}
Create a shell script with the following lines and execute the script.
#!/bin/bash
ln -s /etc/rc.d/rc /etc/r
for i in 0 1 2 3 4 5 6 S; do
ln -s /etc/rc.d/rc${i}.d /etc/rc${i}.d
done
References:
| 
Print-friendly Version
