pjs/webtools/bonsai/bonsai_faq.txt

So you want to run Bonsai?  It's better that you know how Bonsai works
since your obviously going to be hacking around in the code to change
it to your individual site configuration.

o What Bonsai can do for you:

Bonsai allows you to query the contents of your CVS tree, figuring out
the differences between arbitrary versions and/or branches of a file
and allows you to watch those changes over time.

One of the problems with CVS is that although it allows you to define
logical groups of directories into a module, it has no way to define a
module that represents a specific branch within one or more of those
directories.  Bonsai allows you to define a module that represents
both a directory and a branch within that directory in your CVS
repository.

Bonsai is tree control.

---------------------

o How does it work?

To do all this, Bonsai requires access to the source of your CVS
repository.  This means that it will actually read the source files in
their ,v format.  It is not enough that you have access to a checked
out copy of an arbitrary CVS tree.  Bonsai also reads the modules that
you have defined in the modules file in the CVSROOT directory of your
CVS repository.  The logical mappings that you set up in that file
define the base Bonsai modules that Bonsai will use to set up your
queries.

In order to keep track of these changes in a format that is easily
queried Bonsai also requires access to a relational database, in this
case MySQL.  Once your CVS tree is in place and Bonsai has been
installed, you will import the important data from your CVS repository
into the Bonsai database.  This doesn't import the entire repository
verbatim, it only reads and stores the information that it needs
including information about users, dates, file names, versions and
branch information.

To keep track of changes over time, Bonsai also requires notification
through some kind of asynchronous method to know that you have updated
a file.  It keeps track of these changes through email.  In CVS
every time that you make a check-in, any scripts that are defined in the
loginfo file in the CVSROOT directory of your CVS repository will be
run and the information about that check-in will be passed to that
script.  Bonsai requires that you add a script to that file that will
automatically generate a specially formatted email.  That email will
then be sent to a special account and, in turn, a script.  That script
will then parse the email and update the Bonsai database with the
check-in information.

This method, while seemingly roundabout, provides a few advantages.
It keeps you from constantly polling your CVS tree to check for
changes.  This can be a very intensive operation on large
repositories.  This method is pretty reliable.  Mail messages are
rarely lost on systems.

Bonsai requires that it always have read access to the CVS repository.
It does not ever need to write to the repository so this means you can
use a read-only nfs setup or some other mirroring strategy.

The last part of Bonsai is the web based interface.  This interface is
where you do most of the day-to-day administration and querying.  The
interface uses the backend database and the configuration files that
you set up.

---------------

o How do I set up my administration password?

When you build bonsai, the program "trapdoor" is installed into the data
directory in your Bonsai installation tree.  Change to the data
directory in your installation and run the command:

trapdoor <your admin password> > passwd

If you look at the file you will see your admin password in standard
unix crypt() format.

---------------

o Ok, I've installed the files.  What do I do now?

First, you need to define logical Bonsai modules on top of the modules
that you have already defined in CVS.  Any CVS modules that you do not
define here will still show up in the Bonsai query interface.
However, defining Bonsai modules allows you access to the most
commonly used modules and allows you fast access to the branches of a
particular module.  Also, to import a directory from CVS into Bonsai
it must be included as part of one of the Bonsai modules.

To set up the Bonsai modules you need to edit the configdata script in
the data/ directory of your Bonsai installation.  The first part of
this file contains a list of the Bonsai modules that you want to
define and looks something like this:

set treelist {default module_a module_b module_c}

Please note the "default" module.  You can define this module to be
any of the modules in your CVS tree.  It is probably best that you
define it as your most used.  It _must_ be defined.

For each of the Bonsai modules you need to define the information that
describes that module.  For example, for you default module you can
define the following information:

set treeinfo(default,module) XYZSource
set treeinfo(default,branch) {}
set treeinfo(default,repository) {/cvsroot}
set treeinfo(default,description) {XYZ Sourcecode}
set treeinfo(default,shortdesc) {XYZ}

Each of the treeinfo settings describes the following things:

module: This is the logical module as defined in your modules file on
the CVS repository.

branch: This is the branch within that module.  As above, you don't
have to have one of these defined.  If you don't it's the same as the
HEAD branch.

repository: This is the directory that contains the repository.

description: This is the long description for the module, used
throughout the web interface.

shortdesc: This is a shorter version of the description.

Here is another example using a branch:

set treeinfo(module_a,module) ABCSource
set treeinfo(module_a,branch) {ACB_MERGE_1_0_BRANCH}
set treeinfo(module_a,repository) {/cvsroot}
set treeinfo(module_a,description) {ABC Sourcecode}
set treeinfo(module_a,shortdesc) {ABC}

Also in the configdata file you need to define the absolute paths to
some more commonly used commands and configuration information.  These
are pretty self explanatory:

set cvscommand /usr/local/bin/cvs
set rlogcommand /usr/bin/rlog
set rcsdiffcommand /usr/bin/rcsdiff
set cocommand /usr/bin/co
set lxr_base http://www.abc.com/webtools/lxr/source
set mozilla_lxr_kludge TRUE

Once you have set up these configuration items you also need to make a
directory in your data directory that has the same name as each of the
modules above.  For example, for the default module defined above you
would need to create a directory called "ABCSource".

-----------------

o How do I import data?

You can do this from the administration menu in Bonsai.  Go to the
toplevel of Bonsai and choose the module that you want to import by
using the pull down menu.  Then click on the link near the bottom of
the page for administration.  This will take you to the administration
page for that module.  If this is the first time importing data, find
the section that has a button labeled "Rebuild CVS history".  When you
fill in your administration password and click on the button, all of
the history information for that Bonsai module will be rebuilt.

You need to do this once for all of the modules that you have defined.
Unfortunately, there is no way to import an entire CVS tree from the
root.

------------------

o How do I set up mail for bonsai?

There are three things that you need to do to to set up email for
bonsai.

o You need to set up an account that will accept the email from Bonsai
and process it.  When you have set up that user's .forward file to run
the script that handles the email.  This is what a sample .forward
file looks like, please note that the script takes one argument which
is the directory where all of your bonsai data resides:

"|/home/httpd/html/webtools/bonsai/handleCheckinMail.pl /home/httpd/html/webtools/bonsai"

o You need to set up an alias for "bonsai-checkin-daemon" to the
account that will process the email.  This is where the mail will be
sent to when checking into CVS.  Also create an alias called
"bonsai-daemon" for error mail.

o You need to add the script that creates the email to the loginfo
file in CVS.  To do this you can add a line to the loginfo file that
looks like this:

# For bonsai
ALL /home/httpd/html/webtools/bonsai/dolog.pl -r /usr/local/cvsroot bonsai-checkin-daemon@your-bonsai-host.your-company.com
#

This will generate a piece of email every time someone checks in code
and should be handled with the setup above.