Back Home
  BugRat Installation Notes - Read Me FIRST!

Release 2.5 February 12, 2001

REQUIREMENTS

All of these JAR files are included in the WEB-INF/lib directory of the WAR distribution file.

CURRENT BUGRAT USERS

BE CERTAIN TO READ THE RELEASE NOTES!

Several changes have been made to BugRat that will affect your database. Specifically, several name changes were made to tables and fields. I hope you will not have too much trouble making these changes to your existing database. Furthermore, object ids are no longer generated using MySQL's autoincrement feature. They are now managed by BugRat. This means that you will need to run one of the Admin commands before you start using the database. This will generate the id table that BugRat needs.

IF YOU DO NOT READ THE RELEASE NOTES, YOU WILL BE VERY SAD!

If you are creating a brand new BugRat database using the schemas included with this release, then these changes obviously do not affect you.

Also note that there are new properties defined in BugRat to make it more flexible. You should review the properties defined in the file 'sql/defproperties.sql' to see if there are any new properties that you want to define in your database. Use the admin property edit commands to edit these, or use your favorite SQL tool.

THE SUMMARY

THE DETAILS

BugRat consists of a number of distinct "pieces" that you must drop into place in order for BugRat to function properly as a whole. These pieces are:

DATABASE

BugRat requires an SQL database, accessible via JDBC, to function, as that is where it stores all of the data. The distribution comes essentially configured to use MySQL, an excellent database, utilizing the MM.mysql driver available via . The driver's JAR is included with the distribution.

BugRat uses a single database, typically named 'bugrat'. You may name the database any name, as long as you configure the servlet property 'jdbcUrl' to point to the database name that you use.

The database contains 23 tables (25 if you count the auth databases). The file 'sql/schema/'mysql.sql' contains the MySQL schema for the BugRat database. There is also a schema file for Oracle. If you are using a database other than these, you will need to adjust that SQL to fit your database product.

The two tables, 'adminusers' and 'admingroups', are used for apache MySQL authorization, if you choose to use that method for authentication when the BugRatAdmin servlet is accessed. Otherwise, you need not concern yourself with these tables. Or, you could use them for your own auth mechanism if possible.

SCHEMA

The distribution includes a schema for MySQL and Oracle. These schema are located in 'sql/schema/' directory. If you are using a different database server, modify this file to match your server's SQL syntax. If you send the new sql to me at , I will include it in future releases.

CONFIGURATION

BugRat provides you with a serious amount of configurability. In fact, vitrually every field in BugRat is configurable. You can give unique values and names to severity levels, define multiple levels of confidence, and so on.

Typically, however, most installations only configure the projects, categories, and subcategories, while leaving all of the other fields configured to the defaults that come with the distribution.

The distribution includes a series of sql files in the 'sql' directory that will define a reasonable default configuration. The file named 'defconfig.sql' defines default values for the Class, Severity, State, Priority, and Confidence fields. You can use these as-is, or adjust them to meet your needs. The file 'gjtconfig.sql' is the configuration used for the Giant Java Tree.

PROPERTIES

BugRat stores a number of properties in the database that determine how the servlets operate (for instance, whether certain features are disabled), as well as the output of the webpages generated by the servlets. In fact, many of the properties are required in order for the servlets to function properly.

The file named 'defproperties.sql' defines the properties required for the servlets to function. These properties are reasonable defaults and are satisfactory for most installations. Thus, you should simply run the sql to load up the defaults, then use updates to change the properties you wish to customize.

CATEGORIES

BugRat manages a hierarchy of reports and bugs based on the idea of projects with categories broken down into one level of subcategory. BugRat allows you to complete customize these projects, categories, and subcategories via the database.

The file named 'gjtcats.sql' defines projects, categories and subcategories for the Giant Java Tree. It is a good example to begin with. You should use this file as a starting point and edit it to meet your needs, then use it to load the database.

The file named 'examplecats.sql' defines an example project.

NOTE that the hierarchy of the categories is implied by the names. A project will have the value "." for the category and subcategory fields, while a category will have a value of "." for the subcategory field. Subcategories use full names in all three fields. Be sure that you get this correct, or BugRat will not recognize your hierarchy.

You may also create categories in the Admin servlet.

THREE SERVLETS

Why three servlets? I mean, we could have just as easily rolled everything into one servlet and made everything much simpler. Right?

First, please remember that BugRat was developed for the GJT in 1998, with jdk1.1.4 and servlet API 1.2 (I think). It was the dark ages. There was no Java 2, JSP, web.xml (there was no XML). If BugRat were to be designed today, it would be (is) very different.

As you will note, the classes for the three servlets, and their superclass BugRatServlet, are quite large in terms of lines of code. Rolled into one class, the result would be monstrous. The obvious fix is to move to JSP pages. However, before I perform that level of refactoring, I wish to consider better alternatives.

More significantly, authentication would have been less versatile had we used the single servlet model. As it is designed now, you can use no auth, the same auth for all three, or custom authentication for each servlet. In other words, you can allow only the developers to use admin, which provides the ability to link reports to bugs, edit bugs, etc., while allowing anyone on the net to use report to submit reports, and viewer to view the database. Or you could limit admin to developers, report to anyone on the web, and the viewer only to in-house employees and developers. We could not see any advantage of further subdividing the servlets beyond the three.

However, please note that BugRat 3.0, currently being worked on, will be a complete refactoring of the servlets to use a single servlet that drives lightweight command objects, which in turn build XML, which will then be processed via XSLT to produce the HTML. This major refactoring will make BugRat a commercial-quality package that is easily reconfigured and whose presentation can be changed without ever touching the code. Do not expect this to be released anytime soon, as it requires that I reach unemployment nirvana, which does not look highly probable these days.

BugRatViewer

The BugRatViewer is the servlet most users will use when viewing, browsing, searching or otherwise accessing the database in read-only mode. Only if configured to do so will users be allowed to add comments to reports in this servlet. The BugRatViewer is installed the same as the other two, which is described in detail below.

BugRatReport

The BugRatReport is the servlet used to report bugs. That is, bug reports gets its own servlet. This servlet basically does nothing but accept incoming bug reports in various and sundry ways.

BugRatAdmin

The BugRatAdmin is the servlet most developers will use. BugRatAdmin has all of the features of BugRatViewer, as well as the additional administrative functions, such as editting reports and bugs, adding comments to reports and bugs, changing configuration properties, etc.

Servlet Properties and Parameters

You must modify the file WEB-INF/web.xml for your installation, once your app server has unpacked the bugrat.war file. Or you can unpack it and edit it. Or you may edit the file in the war file directly. However, you do it, the file must be modified for your setup. Please see the comments in the web.xml file for details on what to configure and how.

The web.xml file has a long comment at the beginning to assist you in editting the file. Please read them!

EMAIL FILTER

BugRat includes a Java application that can act as an email parser to support the submission of bug reports via email. If you wish to use this filter, you must compile the application and install it as the filter for whatever email alias you use for bug report submission. You will need to configure a few properties in the database so that the email application knows things like the email address it is based on.

This class is designed as an email filter, so it simply needs the email to be available via stdin. This is typical for programs like procmail, which redirect incoming email to various filters. You may also funnel email into the class with an entry like the following in your /etc/aliases file (if you are working under UNIX that is):

   bugreport: "| ~bugrat/bin/bugratmail.sh"

Where bugratmail.sh looks like the following:

   #!/bin/sh

   CLSPATH=/usr/lib/jdk-1.1.5/lib/classes.zip
   CLSPATH=$CLSPATH:/usr/local/java-lib/jar/activation.jar
   CLSPATH=$CLSPATH:/usr/local/java-lib/jar/mail.jar
   CLSPATH=$CLSPATH:/usr/local/java-lib

   java -classpath $CLSPATH org.gjt.bugrat.mail.MailReader \
        --jdbcUrl "jdbc:..." --jdbcDriverClassName driver.class.name

The following lists the properties that you need to configure in the database. The first two global properties are used by the servlets as well. The second two are specific to the email filter.

   global.defaultReportState       - The default report state
   global.defaultReportConfidence  - The default report confidence setting
   bratm.adminAddress              - The email address of the BugRat admin.
   bratm.robotAddress              - The email address of the filter itself.
                                     Used in help page to tell users where
                                     to email bug reports.

BUGRAT CLIENT

DEPRECATED

The client was an application that is designed to be a full fledged client for the BugRat database. However, we soon discovered the power of servlets combined with HTML, and let the client mothball. It still had potential as an administrative tool, as it provides a slightly better interface for those type of functions. However, it was more work and maintenance. So we mothballed it.

DBI

BugRat uses a pachage org.gjt.bugrat.dbi to abstract away the access to persistent storage. The DBI package is access by the objects that are defined in org.gjt.bugrat.db. Currently, there is a JDBC layer, as well as one that allows for tunneling through HTTP for clients. However, the latter has never been fully implemented and is deprecated.

In the future, I may provide a DBI package that implements the BugRat persistent storage on top of EJB. Don't hold you breath...

Anyway, you need to be aware of the DBI layer if you wish to work with the code, but otherwise can ignore the fact that it exists.

PROPERTIES

NOTE - YOU MUST LOAD THE PROPERTIES INTO THE DATABASE.

These are set in the database in table 'properties'. These are all defined in the file 'sql/defproperties.sql'. YOU MUST LOAD THESE into the database. The proper way to do this is to edit the file to your needs, and then use a tool to execute the sql to load it into the database. A few of these are listed here, but the defproperties.sql file is always the best place to look. The file is loaded with comments. You may wish to simply load the defaults into the database without editting defproperties.sql. Then you can use the admin servlet to edit the properties via a web page.

There are many more. The best documentation for these properties is in the 'defproperties.sql' file itself. PLEASE read through these comments if you have questions about the properties. If the comments do not help you, then please email the mailing list.

The properties can also be listed by going to the admin servlet and clicking on the link to list them. However, this list depends on your having inserted the properties into the database via the defproperties.sql file, or its equivalent.

tim.
Tim Endres, <time@trustice.com>
http://www.gjt.org/pkg/bugrat/


Back Home