JBoss Community Archive (Read Only)


Building RHQ


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.

Manual Method

  1. Download the latest release of Maven 3.x from http://maven.apache.org/download.html.

  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

Package Manager Method

On Fedora 21, installing maven through yum package manager gives you a minimum of Maven 3.2.2, and does much of this configuration for you.

$ sudo yum install maven

In the ~/.bashrc file, the following info is present after installing Maven:

export M3_HOME="~/opt/build/apache-maven"
export PATH="$M3_HOME/bin:$PATH"
export MAVEN_OPTS="-Xms256m -Xmx1024m -XX:MaxPermSize=512m"

Update the MAVEN_OPTS parameter values according to the guidance in the Manual Method procedure and save changes to complete this step.

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 https://github.com/rhq-project/rhq/

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 http://git-scm.com/download.

  • Eclipse - Eclipse now hosts the git plug-in which provides some of the git features. For info on the Eclipse git plug-in, see http://www.eclipse.org/egit/.

  • 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. In addition to the rhqadmin user and rhq database created as part of the PostgreSQL instructions, configure another database called "rhqdev":

  3.  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.

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

    cd ~/projects
  2. Clone the RHQ source from the git repo:

    git clone git@github.com:rhq-project/rhq.git

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

    git clone https://github.com/rhq-project/rhq.git
    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:

    $ cat  ~/.ssh/config
    Host github.com
    IdentityFile id_github_rsa
    User joedev

    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. In summary:

    1. Copy over the settings.xml file from the RHQ Git repo.

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

    3. Configure JBoss.org passwords to access the repositories.

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

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

    cd ~/projects/rhq
  4. Build RHQ:

    mvn -Penterprise,dev -Ddbsetup -DskipTests install
    • 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:

cd <rhq-root>/modules/enterprise/server/appserver/target/rhq-server-<version>/bin

If using the dev-container:

cd <rhq-root>/dev-container/rhq-server/bin

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:

> ./rhqctl install

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>:

    ./rhq-server.(sh|bat) console
    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>:

    cd <rhq-root>/modules/enterprise/agent/target/rhq-agent-<version>/bin

    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:

cd <rhq-root>/modules/enterprise/remoting/cli/target/rhq-remoting-cli-<version>/bin
./rhq-cli.(sh|bat) -u rhqadmin -p rhqadmin

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:

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-11 13:00:52 UTC, last content change 2015-02-18 04:15:04 UTC.