Skip to end of metadata
Go to start of metadata

Introduction

The normal method for installing FusionReactor into a J2EE container is to use the FusionReactor Administration Manager's Instance Manager.  This page, located in Instances -> Instance Manager, allows you to easily administer all instances present on a single machine.

If FusionReactor doesn't detect your instance, you may have to install it manually.  There are some caveats to this process:

  • The instance will not be displayed within the Instance Manager (IM).
    • You won't be able to use the IM to administer it.  Internal webserver port, IP address and the "Bind to all interfaces" flag will only be changed by editing the fram.conf file (more on that later).
  • The instance will be unable to use the FusionReactor Administration Manager to offload the zipping of logfiles, or the shipping of logfiles to FusionAnalytics.

Procedure

This procedure has been developed for Unix-type operating systems, including Linux.  FusionReactor may be installed manually on windows, by changing the corresponding paths.  A Windows-specific template configuration is available, and this is noted later in this procedure.

Prerequisites

The following list outlines the prerequisites which must be fulfilled prior to beginning this procedure.

  • The target J2EE container must be installed and running.
  • If you have previously installed FusionReactor 3.x manually, this must be uninstalled.
    • The FusionReactor filter definition, which is inserted usually in a web.xml (or default-web.xml) must be removed.
    • The FusionReactor installation folder (Unix: /opt/fusionreactor, Windows: C:\FusionReactor) must be removed.
  • You should know in which file your J2EE server defines its servlets and filters.  You'll need to know this in order to add the FusionReactor filter later.

This will give a clean environment in which FR4 can be installed.

Installing FusionReactor Administration Manager

The FusionReactor Administration Manager, or FRAM, is a cut-down version of FusionReactor which runs inside its own server, and provides administrative and monitoring functionality for other FusionReactor instances.

Although, as a manual install, you won't be able to take advantage of these functions, FRAM does contain an instance template which you can use to create a manually-installed instance.

  • Unix users who do not have X-Windows or another GUI available to them can run the FusionReactor 4 installer in command-line mode (available in Windows, Linux and Solaris). Simply start it with something like ./FusionReactor_linux_4_5_0.sh -c
  • Unix users with a GUI available, and Windows users, can proceed through the graphical install wizard.

After the wizard completes, and assuming default answers, the FusionReactor Administration Manager will be installed into /opt/fusionreactor (c:\FusionReactor on Windows).

It is not strictly necessary to start FRAM, but if you wish to do so, it can be started using the shell script (/opt/fusionreactor/tomcat/bin/framd start), or by starting the FusionReactor AM service on Windows.  If you picked the default port, the service will be available in your browser at http://localhost:8087/.

Installing a Manual Instance

FusionReactor Administration Manager includes a template instance which you can customize.  The three main steps are:

  • Creating a new instance folder and customizing the configuration.
  • Inserting the filter definition (a small snippet of XML) into your J2EE container's web.xml (or default-web.xml) file.
  • Copying the fusionreactor.jar file to a location accessible by your J2EE container instance.

Creating a New Instance Folder.

For the purposes of illustration, we will be installing a manual instance into Adobe's ColdFusion server, located in /opt/coldfusion9.

  • Locate the supplied instance template folder. This will be in /opt/fusionreactor/etc and is called instance-template.
  • Copy this template to /opt/fusionreactor/instance, and rename it to a unique name.  This is the the instance name.
    • In our case, we're going to rename it to cf9.

Customizing the Instance

Within the /opt/fusionreactor/instance/cf9/conf folder, you will see two subfolders, unix and windows.

  • Copy either the contents of the unix or the contents of the windows folder to cf9/conf.

You should now have a reactor.conf and a filter-def.xml file in the conf folder.

  • Open the reactor.conf file with an editor.
  • Search for all occurences of the string __INSTANCENAME__and replace them with the name you chose above.
    • In our case, this is cf9.
  • If you have installed FusionReactor in a location other than the standard /opt/fusionreactor (C:\FusionReactor):
    • Search for all occurences of the installation folder (/opt/fusionreactor) and change them to your install location.

The internal web server is configured in the file fram.conf.

  • Open the fram.conf file with an editor.
  • The internal webserver, allowing access to FusionReactor over a port independent of your main webserver, is controlled using the webserver.* keys.

Key

Meaning

webserver.active

Whether the internal webserver is made available.  If not, FusionReactor will be available over your main webserver under http://localhost/fusionreactor.

webserver.address

The IP address to which the internal webserver should bind.

webserver.all

Whether the webserver should bind to all addresses.

webserver.port

The port on which the webserver listens.

Perhaps most important is the last key: webserver.port.  You must ensure you use a port here which is not in use by any other application.

Adding the Filter Definition

The file filter-def.xml contains an XML snippet which must be added to your J2EE container's web.xml file.  You should ascertain the location of this file by referring to the container's documentation.

  • Open the filter-def.xml file.
  • Copy the whole content of this file (a filter block and a filter-mapping block) into the clipboard.
  • Open the filter/servlet definition file.
    • In ColdFusion's case, this is /opt/coldfusion9/runtime/servers/coldfusion/SERVER-INF/default-web.xml.
  • Below the web-app start tag, just before the first filter definition (if one is present, if not, just before the first servlet definition), paste the complete content of the clipboard.
  • Customize the __INSTANCENAME__ placeholder to point to your newly-created instance folder.

You should now have inserted the FusionReactor filter and filter-mapping block just prior to the first filter (or servlet) definition.

Copying the fusionreactor.jar file

Within the folder /opt/fusionreactor/etc/lib, you'll find a copy of the fusionreactor.jar file.  This must be copied to somewhere visible to your J2EE server's webapp instance.

* In our case, we copy the file to /opt/coldfusion9/runtime/servers/coldfusion/SERVER-INF/lib/.

 

Finally, start your J2EE container, and watch its standard-out and standard-error logs.  If anything is misconfigured, you should be able to start debugging the problem from the output presented there.

  • No labels