Microsystems Technology Laboratories > OpenCoral
 

Install xReporter

Assumptions

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.

Note
Some of you have previously installed an earlier J2SDK1.4.2-compatible version of xReporter. That installation predated these instructions. As a result this current documentation covers ONLY a fresh installation of the newer JDK1.5.0-compatible version of xReporter. If you have previously installed the older version of xReporter and are wishing to upgrade, you should start with the instructions in Section Upgrading from a J2SDK1.4.2-compatible to a JDK1.5.0-compatible version of xReporter.

Download Source

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
In the above command, the -r <tag> flag is only needed if you are checking out a specific tagged version of the coral-xr module. While we have made limited use of tags in coral-xr, in most cases you likely wish to check out the latest revision of the main branch. If you wish to check out the latest revision of the main branch, you can use the flag: -r HEAD.

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

Database Considerations for Running xReporter

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.
Note
If you are running Postgresql, you need to run a script to give read access to all tables to the reader user. It is probably a good idea to re-run this script to insure that the reader has read access to all tables. This script may be found in the opencoral source tree as opencoral/src/sql/Postrges/patches/grant_all.sh.

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.

Note
If you think that you have added a new report, but it does not appear in your list of reports, it is likely because you have failed to add it to the accesscontrol table that is owned by rptmgr. The accesscontrol table has two columns named report_id and user_role. If you define a new report named my_new_report.xml that defines the id for that report as "my_new_report" and you wish that report to be accessible to everyone (that is role = "active") then you would need to issue the SQL command: INSERT INTO accesscontrol (report_id, user_role) VALUES ('my_new_report', 'active');. Of course, some reports will be visible to more than one user_role, in which case there would be multiple entries for the my_new_report report_id.

Configure xReporter and Third Party Components

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
Note
You need to make sure that your DISPLAY enviroment variable is set and, if you are running this from a different machine, you may need to also run the appropriate xhost +xreporter_machine_name to allow windows on the machine on which you are installing coral-xr to be displayed on the machine on which you are running.

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)
Note
xReporter and xReporter-cocoon revision numbers appear both as 3-digit numbers such as 628 and 780 as well as numbers that appear to be more "version-like" such as 1_3. This is because we have extracted the xReporter packages from the xReporter repository and, in some cases, it is only available as a specific SVN revision and in other cases it is available as a fully-tagged release. Nomrally, the most recent releases or revisions will be listed first in the pulldown menu with older revisions appearing lower on the list. In the case of release 1_3 (the latest tagged release from the xReporter developers), it corresponds to revision number 811.

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.

Compile, Install, and Test Third-Party Components

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
Note
In all of these commands we make use of a pipe and the "tee" command that will redirect standard output (stdout) and standard error (stderr) not only to the screen but to the named log file. This makes it easier to find any problems if they occur. I believe that the above syntax will work for either the Bash shell or for the Korn shell (ksh). If you are using csh, I believe that the equivalent syntax to the above command is: ant tomcat |& 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.

Note
The above instructions assume that you have specified Tomcat6 and are using the default Tomcat port of 8080. If you are using Tomcat 5.5, for example, you would specify the start scripts by replacing tomcat6 with tomcat5.5. If you are using a non-standard Tomcat port (and specified in the configurator), you would point your browser to http://localhost:${tomcat_port}.

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
Note
This is a lengthy set of ant targets to build all of these components. You can effectively call all of those targets in sequence (and collect all of the logging in a single, large log file) by issuing the command: ant extras 2>&1 | tee extras.log. While that is a bit quicker and easier, it also makes it easier to overlook a problem in the installation of these important third-party packages.

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.

Compile and Install xReporter

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
Note
Reports live in the ~coral/coral-xr/reports directory and are all documents in that directory with an XML extension. Phoenix reads the reports from that directory directly and, by default, reads those files every 10 seconds if they have been changed. At the moment, we do not properly support site-specific reports. As people begin to add site specific reports we will likely develop an improved mechanism for supporting site-specific reports.

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