Skip to end of metadata
Go to start of metadata


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 do not want to build RHQ from source, you can instead download a binary distribution.

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.
  1. Download the latest release of JDK 7 available for your OS from either Oracle here or OpenJDK and install it.
  2. 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.
  1. Download the latest release of Maven 3.x from
  2. Unzip it somewhere on your system (e.g. C:\opt, /opt/maven).
  3. Set the following environment variables in your .profile (UNIX) or System environment (Windows):
    • MAVEN_HOME=maven_install_dir
    • MAVEN_OPTS="-Xms256M -Xmx768M -XX:PermSize=128M -XX:MaxPermSize=256M -XX:ReservedCodeCacheSize=96M"
    • PATH=$MAVEN_HOME/bin:existing_PATH

Install Git

RHQ uses git for source code control. In order to download ("checkout") the sources, you need to have a git client installed.

You may browse the RHQ git repository at

Access to the git repository can be done via the git command line or via a plugin to your IDE.
To run git commands independently of your IDE, you can install git from

  • Eclipse - Eclipse now hosts the git plug-in which provides some of the git features. For info on the Eclipse git plug-in, see
  • IntelliJ IDEA - IntelliJ 9 and later has built-in support for git.

Install and Create Database for PostgreSQL

  1. See the PostgreSQL Quick Start Installation Guide to install and configure PostgreSQL
  2. Make sure to create the rhqadmin user and rhq database. Note: to ensure the initial mvn build below succeeds, you also need to have created a database called "rhqdev".

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.
  1. Open a command prompt and cd to the directory where you want the RHQ sources to live, e.g.:
  2. 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 properties
    Note: 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

  1. Make sure you have set up the settings.xml file as described in Advanced Build Notes including uncommenting the postgres profile.
  2. Make sure you have the Databases set up 
  3. Open a command prompt and cd to the directory where the RHQ sources live, e.g.:
  4. Build RHQ:
    • 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.

Also, see Advanced Build Notes for more on using the dev-container, if applicable.

Running RHQ (Version 4.7-)

  1. First start the RHQ server, which is built to <rhq-root>/modules/enterprise/server/appserver/target/rhq-server-<version>:
    Windows NOTE
    You 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.
  2. 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.
  3. Point your browser to http://localhost:7080 and login as user rhqadmin, password rhqadmin.

Run a Local RHQ Agent

  1. Next start the RHQ agent, which is built to <rhq-root>/modules/enterprise/agent/target/rhq-agent-<version>:
    The agent uses Java preferences which stores settings in the Windows registry (if on Windows) or $HOME/.java (if on UNIX). To purge the settings, run with the -L option.
  2. Once the agent is fully started, a platform should appear in the autodiscovery UI page (under the main Inventory view); import this platform into RHQ's inventory.

Run the RHQ CLI

You can also run your build of the RHQ CLI:

See Running the RHQ CLI for more information about the CLI environment.


If you want to contribute to RHQ, you can load the code base in your favorite Java IDE. We have some tips for the big two here:

s s Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.