Software Requirements

The following table lists the software requirements for building and running HQ.

Operating System	Supported operating systems Note: Platform-dependent builds can be created on any supported operating system.
Java Development Kit	JDK 1.5 or 1.6
Apache Ant	1.7.x
JBoss	4.2.3
Database	Supported database versions

HQ Source Tree Structure

The HQ source tree includes all the source code for the HQ, all configuration files, cross-platform installer technology, and accessory jars from various open source projects that HQ depends on.

Section	Description
/bin	Scripts used in HQ and other useful scripts for working with HQ in development.
/build	This generated directory contains the output of the HQ build process. This directory has subdirectories that contain sources generated by XDoclet, XML deployment descriptors, compiled classes, the hq.ear, compiled JSPs, and the agent distribution.
/build_util	Utility ant build files.
/etc	Application property files and JBoss configuration files
/hq_bin	Binary packages of Hyperic projects that HQ depends on. (Sigar for example)
/installer	Support files for the HQ installer technology (which is based on Ant). This directory also contains all the JBoss and Tomcat configuration files which get used in the bundled jboss server.
/plugins	Source code for HQ plugins
/sql	XML files used by DBSetup, the HQ database independent schema definition tool.
/src	Source files for HQ, utilities, and support tools.
/thirdpary	Third party jars required by the HQ build process. Some of these jars are also packaged with HQ or some of the plug-ins.
/ui_plugins	Groovy plugins which provide UI and templating features
/web	JSPs and associated files that make up the HQ web user interface. During GUI development, you can mount this directory as a webapp in a stand-alone Tomcat server to avoid repeated application re-deployment to JBoss.

Environment Settings

Hyperic recommends the following environment variable setting for your HQ build environment.

Database Setup

To run HQ in your development environment you need:

A HQ database instance. For instructions, see Set Up MySQL, Set Up Oracle, Set Up PostgreSQL.
A database user account with permission to create tables and objects
A JDBC database connection string, for example:
- jdbc:postgresql://hostname/database
- jdbc:oracle:thin:@hostname:1521:SID_NAME
- jdbc:mysql://hostname:3306/database

Build Properties

The build process looks for database connection settings in build.properties. Create the properties file in the user's home directory, in a subdirectory called .hq.

If your HQ database runs on PostgreSQL, include these property settings in build.properties:

If your HQ database runs on Oracle, include these property settings in build.properties:

Set ds-mapping=Oracle9i for both Oracle9i and 10g.

If your HQ database runs on MySQL, include these property settings in build.properties:

Building and Running HQ

About the Build System

The HQ build system is based on ant, and is described in {{build.xml}, located in the root of the HQ source tree. The build process performs these functions:

Generate all the support code and deployment descriptor code
Compile all the classes (including generated ones)
Package all the various components
Precompile JSPs (optional stage in development, required for production)
Initialize JBoss instance with HQ specific files (datasources, etc.)
Bootstrap or upgrade database schema
Deployment (only in development)

Build HQ

These targets are simplified into the following Ant invocations. Invoke these in order to produce a development HQ build:

ant all
ant precompile-jsp
ant prepare-jboss
ant dbsetup (or dbsetup-upgrade if you only wish to update the schema)
ant deploy (you can also undeploy first if you wish to clean up the hq.ear file)

After you've completed these steps, JBoss is be ready to be started. The HQ ear file and other configuration changes are applied to the default configuration in JBoss. This is important, since this is the one you'll be starting up in the next step.

Start JBoss

Start JBoss with the run.sh script. If you use an alternate mechanism to start JBoss, make sure it starts the default configuration. Hyperic recommends you run with assertions enabled when developing or testing HQ. To enable assertions, add the -ea switch to run.sh script. The easiest way to do this is to specify the switch in your JAVA_OPTS environment variable. This will add the switch to the script:

Note that the default log4j configuration that ships with JBoss will result in a Hibernate-related exception when starting the JBoss server. See the forum post at http://forums.hyperic.com/jiveforums/thread.jspa?threadID=3777&tstart=0 for more information. To work around this issue, set the log level of Hibernate packages to INFO in the JBoss default server log4j configuration.

Start the HQ Agent

The agent directory in the build directory in your HQ tree is a fully packaged no-JRE agent distribution. You can install agents on other machines by copying the agent directory there, and then point them to your development setup. To start the agent, invoke hq-agent.sh or hq-agent.exe from the agent directory. The first time you do this, the agent will query you for the connection information it needs to communicate with the HQ Server.

Log in to HQ Server

Once the HQ Server is running, you can log in to the HQ user interface at http://localhost:7080 using the default admin account username and password: hqadmin/hqadmin.

Resources discovered by running agents should appear in the auto-discovery portlet. If you have problems, visit the HQ Development Forums at http://forums.hyperic.org/jiveforums/forum.jspa?forumID=3.

Build Instructions