Install xReporter

These installation instructions assume that you have no other installed versions of Tomcat, Cocoon, or Phoenix on the machine on which you intend to run xRpoerter. If you have any of these elements running, you will have to be cautious during the installation process to insure that you do not have port conflicts or configuration problems. In particular, this installation process applies patches (in the form of context-sensitive "diff" files) to a number of the Tomcat and Cocoon configuration files. If you are tryint to apply these to a previously installed version of Tomcat or Cocoon, you are likely to encounter problems. In that case, we suggest that it may be preferable to run multiple instances of Tomcat: one for xReporter and another one for other servlet-based applications.

In general, we expect that most people installing xReporter will wish to make use of the bundled versions of Tomcat, Cocoon, Phoenix, and Tomcat Connectors that come as a part of the coral-xr package. These instructions have been written with that in mind.

We assume that this installation process will be run as the user "coral" and that the installation activity will occur in the ~coral home directory. While any directory may be used, some of the listed commands will need to be amended appropriately if you choose to install things in a different location. We also assume that you have root privileges on the machine on which xReporter will be installed.

Finally, we assume that you have an appropriate version of JDK 1.5.0 or JDK 1.6.0 installed and that the environment variable JAVA_HOME points to that location and that $JAVA_HOME/bin is in your PATH environment variable. Additionally, we asusme that you have installed Ant version 1.6.5 (or newer) on you machine and that the ANT_HOME environment variable points to this directory and $ANT_HOME/bin is in your PATH environment variable. If this is not the case, you may follow the installation instructions listed in Section Install and Configure OpenCoral Prerequisites.

Get the source code from CVS (Concurrent Versions System) repository with the following commands to check out the coral-xr module into the coral user's home directory. Note: in the following, "#" and "$" are simply the prompt for the root user and for the coral user, respectively. The prompts on your system may not match these.

# su - coral
$ cd
$ cvs -d :pserver:coralcvs@opencoral.mit.edu:/usr/local/coral-repository checkout -r <tag> coral-xr

Note: to avoid always having to type -d :pserver:coralcvs@opencoral.mit.edu:/usr/local/coral-repository with each CVS command, it is easier to define the environment variable CVSROOT, either on the command line or in your .cshrc or .bash_profile file, as appropriate. If you have been given write access to the CVS repository (because you are developing core Coral capabilities) you will need to use a different definition of CVSROOT, namely, :ext:login_name@opencoral.mit.edu:/usr/local/coral-repository and you will also need to set the environment variable CVS_RSH to ssh.

Although it is not essential, you may wish to add some sudo configuration using the command visudo that will allow the coral user to do a limited set of things (such as to call ant) as the root user. To do this, you should add the following lines to the end of the sudoers file (usually found in /usr/local/etc/sudoers). In this case you should replace the string "your_xreporter_host with the common name of the machine on which you expect to install and run xreporter. Also, if you plan on installing Tomcat 5.5 rather than Tomcat 6, you should replace the string "tomcat6" with "tomcat5.5" in the appropriate locations.

# Host alias specification
Host_Alias      XR_HOSTS = your_xreporter_host

# User alias specification
# User_Alias CORAL is the list of people who can manually start the
# xreporter system by running the appropriate Phoenix and Tomcat start
# scripts.  This MUST include 'coral' and may include you or other
# trusted personnel in a comma-separated list.
User_Alias      CORAL = coral

# Runas_Alias XR_OWNER should ONLY include 'coral'
Runas_Alias     XR_OWNER = coral

# Cmnd alias specification
Cmnd_Alias      BUILD_XR = /usr/local/ant/bin/ant, /usr/bin/make, /bin/cp, \
                           /bin/chmod
Cmnd_Alias      XR_START = /usr/local/tomcat6/bin/startup.sh, \
                           /usr/local/tomcat6/bin/shutdown.sh \
                           /usr/local/phoenix/bin/phoenix.sh

# User privilege specification
CORAL           XR_HOSTS = NOPASSWD: BUILD_XR
CORAL           XR_HOSTS = (XR_OWNER) NOPASSWD: XR_START
                                                                               # Turn off the 'lecture' given before the first use of sudo because
# this will interfere with the automated build and run processes used
# in opencoral.
Defaults:CORAL          !lecture

Assuming that you have already installed Coral, you likely already have the database users and tables that are needed by xReporter. xReporter makes use of two database users:

• rptmgr: the xReporter administrator that checks which roles and, based on those roles, which reports are visible to each xReporter user. In general, this database user will have the same password as all of the other *mgr database users.
• reader: a person running xReporter accesses the database as the database user reader. The reader user should have a separate password from that of the other database users because, as the name implies, the reader only has read access to the database.

Because of changes in the way that Tomcat authenticates users, we need to make a change in the way that the rpt_role table defines roles for normal users. Unless you have installed your version of the opencoral package more recently than December 1, 2007, you will need to change the way that the rpt_role view (is defined.

If you are running a Postgresql database you should issue the following command as the rptmgr database user:

CREATE OR REPLACE VIEW rpt_role (name, role) AS
(SELECT name, 'active' FROM rscmgr.member WHERE active = 1
UNION SELECT member, role FROM rscmgr.lab_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.project_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.account_role WHERE active = 1);

If you are running the Oracle databse, the command is essentially the same with the addition of the "WITH read only" clause at the end:

CREATE OR REPLACE VIEW rpt_role (name, role) AS
(SELECT name, 'active' FROM rscmgr.member WHERE active = 1
UNION SELECT member, role FROM rscmgr.lab_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.project_role WHERE active = 1
UNION SELECT member, role FROM rscmgr.account_role WHERE active = 1)
WITH READ ONLY;

xReporter requires, but the coral-xr installation of xReporter does not use, a table named customers that is owned by rptmgr. Make sure that this table exists before you try to start and run xReporter. Additionally, each report needs to be added to the accesscontrol table. This table controls which roles will be able to see and run each report. You can load a comprehensive set of these role/report pairings by going to your opencoral CVS repository and running the SQL script in opencoral/src/sql/Oracle/patches/rptmgr.reports.10.1.2005.sql or opencoral/src/sql/Postgres/patches/rptmgr.reports.10.1.2005.sql depending on whether you are running Oracle or Postgresql, respectively.

Once you have downloaded the coral-xr module, you want to run the configurator to specify appropriate configuration parameters. This will be started by running the following commands as the coral user:

$ cd ~coral/coral-xr
$ ant configure
$ ant loadProps

When you issue the "ant configure" command, you will be prompted for the name of your site and asked if that will be the default site. In general, this should be the same site that you specified for your Coral installation. If you are uncertain as to that value, you can check the file named conf/.defaultSite in your opencoral source tree. Next, you will be prompted for the default instance. In most cases, as this will be your "production" installation so you can enter the slightly abbreviated instance name of "prod" in response to this question.

Once the configurator has opened, you need to carefully check and set all appropriate proerties although we attempt to set reasonable defaults. For most fresh Linux installs, many of the properties and paths will be set correctly, but you should check each of them. For the third-party packages you likely want to select:

• xReporter Revision: 1_3 (or newer)
• xReporter-cocoon Revision: 1_3 (or newer)
• Tomcat version: apache-tomcat-5.5.23 or apache-tomcat-6.0.14 (or newer). Note: if you have no explicit reason for running Tomcat 5.5, we recommend that you select Tomcat 6.0 as this is the version that is currently under primary development and support at Apache.
• Cocoon version: cocoon-2.1.10 (or newer)
• Phoenix version: phoenix-4.0.4-tiger. Note: in this case both choices are version 4.0.4. However, the JDK1.5.0-compatible version has the "-tiger" extension because JDK1.5.0 was internally named "tiger" at Sun.
• Jakarta Connectors version: tomcat-connectors-1.2.25 (or newer)

After running the configurator, the "ant loadProps" step will prompt you for the Coral Administrative Database password. This is asking for the rptmgr database password and is likely the same as the password of all of the other *mgr database users. Next it will prompt you for the Read Only report user. This is the database password for the database user named "reader" and is likely different from your normal database password.

We are now ready to install the various third-party (that is, Tomcat, Cocoon, Phoenix, and friends) components on which xReporter depends. The first step is to create the appropriate directories (and links to them) where these elements will be installed. This step will also set up the appropriate init.d scripts so that both Tomcat and Cocoon will be started when this machine is rebooted. This step is initiated by issuing the following command as the coral user from the ~coral/coral-xr directory:

$ ant init

To uncompress and intall the selected version of Tomcat, issue the command:

$ ant tomcat 2>&1 | tee tomcat.log

To uncompress and intall the selected version of Phoenix, issue the command:

$ ant phoenix 2>&1 | tee phoenix.log

To uncompress, compile, and intall the selected version of Cocoon, issue the command: Note, this will take a bit longer because we must compile the Cocoon application.

$ ant cocoon 2>&1 | tee cocoon.log

To uncompress, compile, and intall the selected version of Jakarta Tomcat Connectors (AKA JK), issue the command: This will also take a while as the Tomcat Connectors is a C program that is configured and then compiled.

$ ant jk 2>&1 | tee jk.log

You can corfirm that the jk module got properly installed by issuing the command: ls -l /usr/lib/httpd/modules/mod_jk.so and making sure that the mod_jk.so file exists and that it has an appropriate timestamp.

At this point, you should be able to confirm that Tomcat and Cocoon (without any xReporter customization) are running. To do this you need to start tomcat which will, in turn, start cocoon. This can be done either as the root user by issuing the command:

# /etc/init.t/tomcat6 start

Alternatively, as the coral user, you can issue the command:

$ /usr/local/tomcat6/bin/startup.sh

To test that Tomcat is functional, open up a Web browser on the machine on which you are installing coral-xr and point it to: http://localhost:8080. If Tomcat started properly you should see the Tomcat welcome page. To confirm that this is the proper version of Tomcat, click on the "Release Notes" on the welcome page to confirm that the proper version of Tomcat is installed. Next, point the browser to http://localhost:8080/cocoon. If things have gone smoothly to this point, you should now see the Cocoon welcome page.

At this point it is important to stop Tomcat (and with it Cocoon), before proceeding with the remainder of the installation. This can be done either as the root user by issuing the command:

# /etc/init.t/tomcat6 stop

Alternatively, as the coral user, you can issue the command:

$ /usr/local/tomcat6/bin/shutdown.sh

Now we will configure Tomcat and Cocoon in preparation for the subsequent installation of xReporter. This is done by issuing the command:

$ ant tc-configure 2>&1 | tee tc-configure.log

Finally, we wish to configure httpd for SSL (that is, https://) support. There are two things that are needed in order to properly encrypt and decrypt all of your xReporter traffic. First, you will need either a "real" SSL certificate for Apache from one of the certificate authorities such as Verisign or Thawte. If you want to use a self-signed certificate, you can go to the /etc/httpd/conf directory and issue the command: "make testcert". This will generate a public/private key and use that to generate a self-signed certificate which will be located in the file named: /etc/httpd/conf/ssl.crt/server.crt.

Alternatively, if you wish to acquire a "real" SSL certificate, you can generate an Apache-compatible SSL certificate request which can be sent to one of the certificate authorities by issuing the command "make certreq" from the /etc/httpd/conf directory. In this case, your certificate request will be found in the file named /etc/httpd/conf/ssl.csr/server.csr. Once you have received your certificate from the certificate authority, you can copy it into the file named /etc/httpd/conf/ssl.crt/server.crt. Of course, if you already have a SSL certificate for this machine, you may continue to use that.

To properly configure httpd for SSL use, you may issue the following command from the ~coral/coral-xr directory:

$ ant sslConfigure 2>&1 | tee sslConfigure.log

Once you have successfully run the sslConfigure target, you should restart the httpd server.

Now we are prepared to unpackage, compile, and install the two main packages that consitute xReporter: xreporter and xreporter-cocoon. From a functional standpoint, the xreporter portion lives primarily within the Phoenix structure and basically generates the list of reports, processes the input parameters associated with the report request, send the report request to the database, and hand off the largely unformatted result to the xreporte-cocoon package. The xreporter-cocoon package that is a webapp running within the Tomcat/Cocoon framework is primarily responsible for presentation of the resulting report information either in a paged browser format or as either and Excel or PDF file.

We start this process by issuing the following command from the ~coral/coral-xr directory as the coral user:

$ ant xr-seed 2>&1 | tee xr-seed.log

Unless you have overridden the location of the xreporter and xreporter-cocoon packages in the configurator, he xr-seed target starts by unpackaging these two packages in directories named ../xreporter and ../xreporter-cocoon, respectively. In other works, at the end of this step you will find the directories ~coral/coral-xr, ~coral/xreporter, and ~coral/xreporter-cocoon.

Next we build and deploy the xreporter target and the xreporter-cocoon target, respectively, by issuing the following commands from the ~coral/coral-xr directory:

$ ant xr-deploy 2>&1 | tee xr-deploy.log
$ ant xr-cocoon-deploy 2>&1 | tee xr-cocoon-deploy.log

Particularly if you are adding your own reports or modifying existing reports, it is often useful to validate all reports to insure that they contain valid XML. To be more precise, this target checks both that the XML used in the report definition is well-formed and also valid as defined by the xReporter schema. Report generation can be run by issing the following command from the ~coral/coral-xr directory:

$ ant xr-validate 2>&1 | tee xr-validate.log

Congratulations! You have now completed the installation proces and are read to start and test your xReporter installation