This page has instructions for building Hyperic HQ from source.

Software Requirements

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

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.

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 (Recommended Database), 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 and Runtime Properties

The build process and the HQ web app look for configuration properties (including database connection settings) in build.properties. Create the properties file in the user's home directory, in a subdirectory called .hq. This file is required for running the ant task to install the database schema. Properties in this file also override all default properties used by the HQ web app.

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 server.database=Oracle9i for both Oracle9i and 10g.

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

You must specify a default login for HQ in your build.properties file prior to installing the database schema

Building and Running HQ

About the Build System

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

• Compile all the classes
• Package all the various components
• Bootstrap or upgrade database schema
• Deployment (only in development)

Build HQ

HQ follows the normal Maven phases:

Common Usages

• Build a regular distribution (includes all installer and agent bundles)
• Build modules, excluding installer and agent bundles
• Build a specific agent bundle (from dist/hyperic-hq-agent)
• Build a specific installer bundle (from dist/hyperic-hq-installer)
• Build modules (excluding installer and agent bundles) and run integration tests
• Installation into Maven repo

Artifacts

• hq-web/target/ROOT.war
  Deploy this webapp to your Tomcat or tc Server 6.0 container to run HQ server in development. The web app requires a live database with the HQ schema installed. It is currently required that HQ be the ROOT webapp.
• dist/target/hyperic-hq-agent-VERSION-OS.tgz/.zip
  Unpack and run this agent on a managed node by invoking bin/hq-agent.sh start
• dist/target/hyperic-hq-installer-VERSION-OS.tgz/.zip
  Unpack and run setup.sh for a full production install of the HQ server and/or agent

Integration Testing

The tests in the hq-integration-tests module require a live database (PostgreSQL or MySQL) with the HQ schema installed.

Install HQ Database Schema

You will need to install the database schema prior to running the integration tests or deploying the HQ web app.

To install the schema:

After you've completed these steps, you are ready to deploy your application to Tomcat.

Deploy to Tomcat

You can replace Tomcat's ROOT webapp manually, or use the maven Tomcat plugin to deploy to a running Tomcat or tc Server (uses the Tomcat manager webapp).
To deploy:

1. Edit the $TOMCAT_HOME/conf/tomcat-users.xml and add a new user with manager permissions.
2. Add a server configuration called local-tomcat to your ~/.m2/settings.xml file
3. Run the redeploy command

Start Tomcat

Start Tomcat or tc Server with the startup script. We recommend adding the following Java Opts to the setenv file located in the bin directory:

Start the HQ Agent

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 admin account username and password specified in your build.properties.

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.