Build Instructions

Hyperic HQ Build Instructions

This document describes the source code layout for the Hyperic HQ product and provides all necessary background information on how to package HQ for both development and release versions.

Build Requirements

The following table lists the requirements for building HQ. Keep in mind that the released HQ product is supported across many platforms, but the platform dependent builds can all be done from any supported operating system.

HQ Source Contents

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 which HQ depends on.

Building and running HQ in development

This section describes the process of building HQ and getting all the way to the point where you have a standalone functional copy of HQ in your development environment.

Environment Settings

As part of working with the HQ build environment, it is recommended for you to set the following environment variables:

JAVA_HOME=/path/to/your/jdk
ANT_HOME=/path/to/ant-1.7.x
JBOSS_HOME=/path/to/jboss-4.0.3SP1
ANT_OPTS="-Xmx256M -XX:MaxPermSize=128m" (required for XDoclet)
JAVA_OPTS="-ea" (recommended to run with assertions enabled for development and testing)

If you want to run the agent on this machine, you must also set the following environment variables:

HQ_JAVA_HOME=/path/to/your/jdk

Database Setup

Whether you choose to use PostgreSQL, Oracle, or MySQL, you will have to have the following accessible to you in order to properly operate your development HQ installation:

• A database instance (PostgreSQL can be downloaded and installed directly from http://www.postgresql.org)
• A user account which can create new tables and objects in the database
• A JDBC connect string to access the database
  • PostgreSQL ones look like this: jdbc:postgresql://hostname/database
  • Oracle ones look like this: jdbc:oracle:thin:@hostname:1521:SID_NAME
  • MySQL ones look like this: jdbc:mysql://hostname:3306/database
    NOTE: MySQL is supported only on HQ 3.2 and later

Product Build Properties

The build system uses a properties file to define the specific aspects of the environment to be used as part of the build and packaging process. The build.properties file should be placed in the user's home directory, in a subdirectory called .hq.

The minimum contents of the build.properties for a PostgreSQL backed HQ installation are:

hq.jdbc.url=jdbc:postgresql://localhost:5432/hq?protocolVersion=2
hq.jdbc.driver=org.postgresql.Driver
hq.jdbc.user=hq
hq.jdbc.password=hq
hq.server.ds-mapping=PostgreSQL

For Oracle the properties would be:

hq.jdbc.url=jdbc:oracle:thin:@10.0.0.3:1521:HQ
hq.jdbc.driver=oracle.jdbc.driver.OracleDriver
hq.jdbc.user=hq
hq.jdbc.password=hq
hq.server.ds-mapping=Oracle9i

The ds-mapping for Oracle 10g would be Oracle9i and Oracle8 for Oracle 8.

For MySQL the properties would be:

hq.jdbc.url=jdbc:mysql://localhost:3306/hqdb
hq.jdbc.driver=com.mysql.jdbc.Driver
hq.jdbc.user=hq
hq.jdbc.password=hq
hq.server.ds-mapping=MySQL

NOTE: MySQL is supported only on HQ 3.2 and later

Building HQ

The HQ build system is based on ant, and is entirely described in a single build.xml file found at the top level of the hq source distribution. The HQ build process is divided into the following 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)

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 successfully completed these steps, your jboss will 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.

Starting JBoss

In order to start the JBoss server, simply use the run.sh script. If you use an alternate mechanism to start JBoss, make sure the default configuration is the one that is started. When developing or testing HQ, it is recommended that you run with assertions enabled. To do this, add the -ea switch in the run.sh script when starting the JBoss server. The easiest way to do this is to specify this switch in your JAVA_OPTS environment variable. The switch will be added automatically to the run.sh script, like so:

JAVA_OPTS="-ea"

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

Next, you'll want to start your agent. The agent directory that's found inside the build directory in your hq tree is a fully packaged agent distribution. The only thing it's missing is the JRE. This means you could conceivably copy that directory around to other machines to install additional agents and point them to your development setup. In order to start the agent, you simply need to invoke the hq-agent.sh or hq-agent.exe from the agent directory. The first time you do this, the agent will interactively ask you for information it needs to successfully communicate with the server.

Last Steps

Once everything is set up and running, you should be able to visit http://localhost:7080 and log in using the default root username and password: hqadmin/hqadmin

From this point on, you should be able to approve autodiscovery, and have a functional build of HQ in your machine. If you run into any problems consult the HQ Development Forums located at http://forums.hyperic.org/jiveforums/forum.jspa?forumID=3, or subscribe the the hq-dev mailing list. Instructions on how to do this can be found here