Building RHQ

RHQ Project

Building RHQ

The steps described below are designed to allow you to quickly build RHQ in as few and easy 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.

To build RHQ from source and get it up and running, follow the below steps:

Overview

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 following: 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) is not enough.
  1. Download the latest release of JDK 6 available for your OS from here 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=JDK6_install_dir
    • PATH=$JAVA_HOME/bin:existing_PATH

Install Maven

The RPM for Maven2 (2.0.8-3.fc12) in Fedora is too old to work with RHQ. RHQ requires Maven 2.1+ and will need to be installed manually.
  1. Download the latest release of Maven 2.1.x or 2.2.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):
    • M2_HOME=Maven2_install_dir
    • MAVEN_OPTS=-Xms128M -Xmx768M -XX:PermSize=128M -XX:MaxPermSize=256M
    • PATH=$M2_HOME/bin:existing_PATH

Install Git

You may browse the RHQ git repository at http://git.fedorahosted.org/git/rhq/rhq.git

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.x 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.
The latest code now allows for the use of an H2 Embedded Database. So if you do not have or want PostgreSQL installed, you can use the built-in H2 Embedded Database. The H2 Embedded Database is only to be used in a demo or developer environment - it is not to be used for production environments.

Checkout RHQ Sources

  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://git.fedorahosted.org/rhq/rhq.git

    or for developer access:

    Developer access
    git clone ssh://git.fedorahosted.org/git/rhq/rhq.git
    SSH properties
    Note: if your fedora user name is different from the local one or you have a different public key for
    fedora 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 git.fedorahosted.org
IdentityFile id_fedora_rsa
User ADeveloper

    So in this example the fedora user is ADeveloper and the ssh key is in ~/.ssh/id_fedora_rsa

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

Build RHQ

The Maven central repository hosted at maven.org is not a reliable/stable repository. The very first time you attempt to build via mvn, you may get failures due to being unable to download Maven libraries. It is not uncommon to have to run your first mvn build multiple times to get it to fully go through. This should only be a problem the first time you build - once you get all the Maven libraries downloaded and installed in your local repository, they will be used and the need to access them from maven.org will go away.
  1. Make sure you have set up the settings.xml file as described in Advanced Build Notes including uncommenting the postgres profile.
  2. Open a command prompt and cd to the directory where the RHQ sources live, e.g.: 
    cd ~/projects/rhq
  3. Build RHQ: 
    mvn -Penterprise,dev -Dmaven.test.skip=true -Ddbsetup install
    NOTES
    • The first time you build RHQ, it will take 10-20 minutes, because it will need to download dozens of 3rd party dependency jars for both RHQ and Maven itself. However, subsequent full builds should only take 3-5 minutes, shorter if you perform individual module dev builds.
    • "-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
    • The RHQ BuildNumber is set to the git sha1.

    As of 11/20/2009, git is not integrated into our mvn build, so the BuildNumber will be set to 0. This will be fixed in the future.

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

Run RHQ Server

  1. First start the RHQ server, which is built to <rhq-trunk>/modules/enterprise/server/container/target/rhq-server-<version>/bin: 
    cd <rhq-trunk>/modules/enterprise/server/container/target/rhq-server-<version>/bin
./rhq-server.(sh|bat) start
    Because you built using the -Pdev Maven profile, you can also run the RHQ Server container that is built to <rhq-trunk>/dev-container. See Advanced Build Notes for more information on the enterprise and dev profiles
    UNIX NOTE
    The build today does not turn on the proper execute bits so first execute the following: 
    chmod ug+x bin/rhq-server.sh jbossas/bin/run.sh
    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 "start" so you cannot just double-click it from a Windows Explorer window to start it.
  2. Once the RHQ server is fully started, go to http://127.0.0.1:7080/ in a Web browser.
  3. Login as user rhqadmin, password rhqadmin.

Run a Local RHQ Agent

  1. Next start the RHQ agent, which is built to <rhq-trunk>/modules/enterprise/agent/target/rhq-agent-<version>/: 
    cd <rhq-trunk>/modules/enterprise/agent/target/rhq-agent-<version>/bin
./rhq-agent.(sh|bat)
    Windows NOTE
    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 portlet on the Dashboard page; import this platform into RHQ's inventory.
IDE Development
If you want to develop the RHQ platform, you can load the code base in your favorite IDE. We have some tips for the big three Java IDEs:
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.