ARTICLES

Compiling OpenNMS from Source

This article describes how to compile OpenNMS from source. If you have not set up your environment properly, please see here.

Checkout the Code

First of all, the code should be checked out. I usually do this in my ~/dev directory:

git clone https://github.com/OpenNMS/opennms.git

This will create an opennms directory in ~/dev/opennms. Next cd into it: cd opennms.

Build from Source

TL;DR

Regular development

time (./clean.pl && ./compile.pl -U -DskipTests && ./assemble.pl -p dir -DskipTests); say "OpenNMS may be ready for deployment"

When Deploying it somewhere else than locally on my machine

time (./clean.pl && ./compile.pl -DskipTests && ./assemble.pl -Dopennms.home=/opt/opennms -DskipTests); say "OpenNMS may be ready for deployment"

Detailled explanation

The build of OpenNMS is usually split into 3 phases:

  • clean.pl → Removes all previously build artifacts/archives

  • compile.pl → Compiles the root module

  • assemble.pl → Builds the final assembly opennms-<version>.tar.gz

Behind the scenes OpenNMS uses Maven as a build tool. The above scripts roughly translate to the following actions:

  • clean.pl → invokes mvn clean and mvn clean -F opennms-full-assembly

  • compile.pl → invokes a mvn install on the root module

  • assemble.pl → invokes a mvn install -F opennms-full-assembly

Each script has various numbers of arguments and options, which you can show with -h

Full build (step by step)

First navigate to your local git repository

cd ~/dev/opennms

Ensure you are on the desired branch (e.g. develop)

git status

Now do a full build with the following command

./clean.pl && ./comppile.pl -DskipTests && ./assemble.pl -DskipTests -p dir

This will build OpenNMS from source (no tests are executed) and will place all files and directories to ~/dev/opennms/target/opennms-<current-version>.

If you want an archive instead, simply omit the -p dir option

If you want another opennms.home directory, simply define it in the assembly step: ./assemble.pl -DskipTests -Dopennms.home=/opt/opennms -p dir.

Please keep in mind, that if you are building the first time, this may take several hours, because a lot of dependencies must be downloaded.

Running OpenNMS after compilation

After OpenNMS built from Source successfully it must be configured before it can be started.

First configure java:

./bin/runjava -s

and afterwards initialize/update the database:

sudo ./bin/install -dis

Pro Tip: In case you are working on an OSGi bundle it is recommend to link the root user’s .m2/repository directory to the user you build OpenNMS with. This enables you to use the bundle:watch command or manually install missing bundles, which are not located in the system directory.

> sudo su
> mkdir ~/.m2
> cd ~/.m2
> ln -s /home/<user>/.m2/repository repository

Now OpenNMS can be started (i.e. with the -t option to enable the remote debugger):

sudo ./bin/opennms -vt start

The WEB UI should come up after some time at http://localhost:8980/opennms.

How I Build

Regular development

time (./clean.pl && ./compile.pl -U -DskipTests && ./assemble.pl -p dir -DskipTests); say "OpenNMS may be ready for deployment"

When deploying it to a custom opennms.home (i.e. on another machine)

time (./clean.pl && ./compile.pl -DskipTests && ./assemble.pl -Dopennms.home=/opt/opennms -DskipTests); say "OpenNMS may be ready for deployment"

Troubleshooting

If you encounter a dependency download or OpenNMS Maven Repositor issue, try rebuilding at least twice before considering it an actual issue. Sometimes it requires multiple runs before it actually works. This will be solved as soon as the maven repository is populated properly

Running Tests

There will be a topic talking about running the various tests locally. As a general side note however NEVER run ALL unit or integration tests locally. This is what Bamboo is for.