Overview

The steps described below are designed to allow you to quickly build RHQ in as few steps as possible. After you become more familiar with the code base and more proficient with the build system, you should check out our Advanced Build Notes for additional things you will find helpful in working with the RHQ Maven build system.

If you want to get familiar with how each of the individual modules in the source tree contribute to the overall built product, please read the Module Overview.

Install JDK

In order to compile the RHQ source code, you will need the Java Developer's Kit (JDK), which includes javac - the Java Runtime Environment (JRE) will not suffice, since it does not include javac.

Download the latest release of JDK 7 available for your OS from either Oracle here or OpenJDK and install it.

Set the following environment variables in your .profile (UNIX) or System environment (Windows) - you must ensure you set these if you have multiple Java installations on your box, to ensure Maven picks up the correct JDK that you want to use:

JAVA_HOME=JDK7_install_dir

PATH=$JAVA_HOME/bin:existing_PATH

Install Maven

The RPM for Maven found on some Fedora versions is too old to work with RHQ. In this case, you will need to be install Maven manually.

Install and Create Database for PostgreSQL

In addition to the rhqadmin user and rhq database created as part of the PostgreSQL instructions, configure another database called "rhqdev":

postgres=# CREATE DATABASE rhqdev OWNER rhqadmin;

Checkout RHQ Sources

If you plan to submit patches to RHQ, it is best to fork the RHQ source code into your own
repository on GitHub, so that you can send pull-requests later.

Open a command prompt and cd to the directory where you want the RHQ sources to live, e.g.:

Clone the RHQ source from the git repo:

or if your firewall prevents using the git protocol you can also clone via https (much slower though)

SSH propertiesNote: if your GitHub user name is different from the local one or you have a different public key for
GitHub than some default one, you need to specify it to git/ssh.
To do so you can add this to ~/.ssh/config:

So in this example the GitHub user is joedev and the ssh key is in ~/.ssh/id_github_rsa

If you are on Windows, make sure you do not checkout the RHQ code into a directory with a long path, as this will cause errors during the build and startup.

Build RHQ

Uncomment the postgres profile, and either commenting out or deleting totally the other database profiles.

Configure JBoss.org passwords to access the repositories.

Make sure you have the Databases set up, according to the Install and Create Database for PostgreSQL section on this page.

Open a command prompt and cd to the directory where the RHQ sources live, e.g.:

Build RHQ:

NOTES

The first time you build RHQ, it will take up to an hour, because it will need to download many 3rd party dependency jars for both RHQ and Maven itself. Subsequent builds will be significantly faster, especially if you only build specific modules.

"-Ddbsetup" is only required the first time you build; thereafter, the schema will be created in your database, and you won't need to do it again unless a) the schema changes and needs to be rebuilt or b) you want to clean out your database and rebuild the schema.

You do not need to rebuild your container after performing a subsequent -Ddbsetup, but you will want to restart your agent --fullcleanconfig.

The RHQ BuildNumber is set to the git sha1.

If you have been building RHQ for a while and you notice that the versions of any dependencies in the dependencyManagement section of the root POM have changed due to a recent commit, you MUST build from root. If you don't, the {m2_repo}/org/rhq/rhq-parent/{currentVersion}/rhq-parent-{currentVersion}.pom file will be stale, and will be used when resolving dependencies locally, and thus you won't resolve to the latest dependencies. If you don't want to take the "hit" of building from root, you can build ONLY the root module by saying "mvn -N install" from the root, which will update the aforementioned POM in your local repository without building all modules.

If you run into test failures, run with the option -DskipTests so that those will be still built, but not executed. -Dmaven.test.skip will also skip building them and subsequent compilation will fail.

Running RHQ

Because you built using the -Pdev Maven profile, you can also run the RHQ Server container that is built to <rhq-root>/dev-container. See Advanced Build Notes for more information on the enterprise and dev profiles. Typically, developers will want to use the dev-container.

Switch to the RHQ bin directory. If simulating production:

If using the dev-container:

Running RHQ (Version 4.8+)

Starting with version 4.8 RHQ is installed/started/stopped using the new RHQ Control Script. See RHQ Control Script before continuing, but to run RHQ the first time you will basically perform:

This will install the Cassandra storage node, the server, and an agent, and will start them all. You then can further use the control program to start, stop or get status on the RHQ components.

Running RHQ (Version 4.7-)

First start the RHQ server, which is built to <rhq-root>/modules/enterprise/server/appserver/target/rhq-server-<version>:

Windows NOTEYou may want to use the rhq-server-console.bat script - you can double click it to start the server. The rhq-server.bat expects a command line argument "console" so you cannot just double-click it from a Windows Explorer window to start it.

If you did not build with -Pdev, then once the RHQ server is fully started, complete the installation by running rhq-installer.(sh|bat) located in the same directory where the server startup script is found. If you did follow the instructions above (which included using -Pdev), the installer will run for you automatically when you start the server.