Difference between revisions of "Installation:Source"

From OpenNMS
Jump to: navigation, search
(You probably don't want to build from source)
Line 5: Line 5:
  
 
These instructions are recommended for developers interested in building from source.
 
These instructions are recommended for developers interested in building from source.
 +
 +
== These are not '''''upgrade''''' instructions! ==
 +
 +
Attempting to build a newer version of OpenNMS from source on top of an existing install is not supported.  If you are upgrading, back up your data and configs and do a fresh install.
  
 
== Applicable versions ==
 
== Applicable versions ==

Revision as of 15:27, 27 February 2012

You probably don't want to build from source

For most users, it is recommended that you follow the QuickStart guide relevant to your platform, and install pre-built binaries.

These instructions are recommended for developers interested in building from source.

These are not upgrade instructions!

Attempting to build a newer version of OpenNMS from source on top of an existing install is not supported. If you are upgrading, back up your data and configs and do a fresh install.

Applicable versions

This document applies to building the code in "master" (trunk) in Git and OpenNMS 1.8.7 and later releases. For older releases, see Building OpenNMS (Old).

Getting the source

Checking out the Source Code

Maven

A copy of Maven is now included in the OpenNMS source tree.

To get an overview of Maven in general, read Gettting Started and Better Builds with Maven.

Maven dependencies

Maven downloads the dependencies for building OpenNMS from Maven repositories on the Internet.

If you are not connected to the Internet, run mvn with the -o flag to work offline. However, to do that, your local repository (~/.m2/repository) will need to contain all required dependencies, which you will then have to obtain in some other way (typically from some other internet connected host). See the <repository> tags in the top level pom.xml for the places that maven would have looked to find the dependencies.

Modules

The OpenNMS source code has been broken up into sub-modules. Modules can be simple modules that represent the code for a single "artifact" like a jar file. They can also be "aggregate" modules with are container modules made up of sub-modules of their own. Here are some points to help you find things:

  • Each jar module contains a src/main/java directory which contains all of its Java sources. A war or webapp module has its web pages stored at its src/main/web sub-directory.
  • Tests and related code are under src/test/java.
  • Maven also supports "resources" or other files that should be included in jar files such as *.properties and other things. These are stored in src/main/resources (or src/main/filtered if property filters should be run on them first) and src/test/resources (similarly src/test/filtered for filtered test resources).

Preparation

To make sure that you don't run into bug #1873, verify that the "javah" executable is in your path and that it is version 1.5 or later by running "javah -version". E.g.:

$ javah -version
javah version "1.5.0_07"

Make sure you have postgresql-devel and rrdtool-devel installed.

Install jicmp

To build jicmp from source, in addition to the Jicmp tarball you'll also need automake, autoconf, and libtool.

 cd jicmp
 autoreconf -fvi
 ./configure
 make
 sudo make install

This should put jicmp into /usr/local/lib (or /usr/local/lib64 on some 64-bit systems).

Building

There are two scripts associated with building.

compile.pl 
compiles all of the platform-agnostic, non-system-specific OpenNMS jars; this is essentially a smart wrapper around the 'mvn' command. Use this where you would normally use the 'mvn' command.
assemble.pl 
assembles packages of the OpenNMS release, including configuration files, webapps, etc.

Both scripts can be passed a number of options for overriding behavior and environment settings. Run "./compile.pl --help" or "./assemble.pl --help" for details.

Using a HTTP Proxy during build

If you are building on a host that doesn't have a direct internet connection, you will need to edit maven/conf/settings.xml to set your web proxy. I needs to look something like this:

  <proxies>
   <proxy>
     <id>optional</id>
     <active>true</active>
     <protocol>http</protocol>
     <username></username>
     <password></password>
     <host>127.0.0.1</host>
     <port>3128</port>
     <nonProxyHosts>127.0.0.1</nonProxyHosts>
   </proxy>
  </proxies>

Note: Change 127.0.0.1 to the address of your proxy.

Inline

The simplest way to build OpenNMS is by issuing the following command:

./compile.pl
./assemble.pl -Dbuild.profile=dir

This will compile and build all the code and assemble a distribution under target/opennms-${version} and can be run from that location.

Inline with an alternate distribution directory

If you want OpenNMS to be staged to a different directory, you can use this command:

./compile.pl
./assemble.pl -Ddist.dir=$PWD -Ddist.name=dist -Dbuild.profile=dir

This will install it in the $PWD/dist directory (i.e. the directory "dist" as a subdirectory of where you are running this command). Note that because it translates the configuration files, it will only successfully run from that location.

Attached with an alternate distribution directory

To build a distribution so as to run it from a different location, say /opt/opennms, use this:

./compile.pl
./assemble.pl -Dopennms.home=/opt/opennms

This will build a distribution in target/opennms-${version}.tar.gz containing a distribution intended by untarred inside the /opt/opennms directory:

 cd target
 cp -p opennms-*.tar.gz /opt/opennms
 cd /opt/opennms
 tar zxf opennms*.tar.gz
 chmod +x bin/*

Don't forget to clean if you've changed build options

If you've built OpenNMS previously and have changed build options (such as the "opennms.home" property) or performed an update from the source code repository, you'll want to clean the assembly, first:

./clean.pl

If there are pom updates or files getting renamed from one sub-module to another in the source code it's generally a good idea to clean after updating before attempting to rebuild.

Building tools (opennms-tools)

If you want to build one of the OpenNMS tools in the opennms-tools directory, you can go to the directory, opennms-rrd-stresser for example, and run
mvn $target
from there. It will then get and build the necessary dependencies for you. If you ran "mvn install", you will find the compiled tool in the target/ subdirectory. In lieu of the 'mvn' command, you can also run
/path/to/compile.pl
instead.

RPM Packages

You should only have to run:

 ./makerpm.sh

...to build a snapshot RPM with your latest code.

Debian Packages

First, edit debian/changelog and create a log entry for your nightly/snapshot build. Then, just run:

 dpkg-buildpackage

Solaris Packages =

There is a makefile to generate Solaris packages. Just run:

 cd solaris
 make

Running OpenNMS

Now that you have OpenNMS built you can run it.

Fix the Permissions

There is a bug in the dist creation that fails to properly set the execute permissions for scripts. Fix this as follows:

cd <opennms.home>

chmod +x bin/*
chmod +x contrib/*
chmod -x contrib/*.README
chmod -x contrib/opennms.mib

Set the JVM

Before you can do anything else with OpenNMS you'll need to tell which JVM to use. To do this enter the following command:

./bin/runjava -s

If that does not find a suitable JVM for OpenNMS, or if you want to force a specific JVM, you can use this:

./bin/runjava -S <the directory in which your JVM is installed>/bin/java

This will create a file called java.conf in <opennms.home>/etc that contains the java command that will run whenever opennms is started

Set up the database

The next step is to set up the OpenNMS database. Do this using the following command:

./bin/install -dis

This will set up the database for OpenNMS, preserving any existing data. To completely clear the database and start over, DROP your existing database first.

For more information on the flags available to the installer, for example to specify a different name for the database, run

 ./bin/install -h

If this step fails, please check the following:

Customizing the pg_hba.conf file

The pg_hba.conf file controls which machines and users can access the database on a given machine via TCP/IP.

Since that is how OpenNMS accesses the database (via localhost) it is necessary to modify this file to allow OpenNMS to work. The easiest thing to do is to just allow anyone from the localhost to access the database (do not add the last line if your system does not support IPv6):

# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
local all all trust
host all all 127.0.0.1 255.255.255.255 trust
host all all ::1 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff trust

Make sure that no other lines are uncommented in this file.

You will need to stop and restart Postgres after making these changes.

Start opennms

At this point you should be able to start the opennms 'daemon'. As root run this command:

cd <opennms.home>
./bin/opennms start

Setting up the OpenNMS webapp

OpenNMS versions later than 1.3.7 have a built in web application server. Once you have opennms started you can simply browse to http://localhost:8980/opennms and see the webapp front end.

You can also install the webapp in a Tomcat 5.5 server. See the install instructions for Tomcat installation.

View the webapp!!!

Now you may start Tomcat and visit http://localhost:8980/opennms/ to view the webapp! Login as "admin" with the password "admin".

Troubleshooting

See Building FAQ.