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 > 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.