pjs/webtools/tinderbox2/Install

Currently this is Alpha/Beta code, because no one but me is using it
yet (and even I am not using all the features I have tested). If you
are not really comfortable coding in perl I suggest you wait until
more people are using it and we get the minor kinks worked out of the
code and documentation.


To install:

*) The src/default_config directory contains perl libraries which are
specific to an individual users site configuration.  No two users of
Tinderbox will have the identical sets of files.

The files found in default_config are sample files which are used at
Mozilla.org.  Other users are expected to customize these libries and
install the modified libraries in local_config.  Files found in
local_config will be used before any file found in default_config.
The distribution of Tinderbox will never place any files in the
local_config directory as this is assumed to be under local control.

A quick overview of the files:

	TinderConfig.pm: general configuration settings 
		(HTML directories, Log files, implementations of libraries 
		 to use, etc).
	TreeData.pm: version control (CVS, Bonsai) configuration.
	Error_Parse.pm: the regular expressions for identifying
		 errors in build logs.
	BTData.pm: bug tracking configuration
	FileStructure.pm: filesystem (storage) and global/per-project 
		settings. Most users will not have to change this.

*) Run ./configure. When configure is done you will have a Makefile
and a config.out.  Although Tinderbox consists entirely of perl
scripts we must substitute some values into the source code to make it
executable.  You may wish to change the default directories in configure
for some of the makefile variables.  Please read config.out and make
any changes which need to be made for your system.

*) run 'make' to create executable versions of the source code in the
./build directory.

*) run 'make compile_bin_code' to ensure that the code will compile when
it is installed.

*) run the test programs as described in /build/test/ReadMe to ensure
that you have configured the program correctly.

*) run make install, to install Tinderbox on your system.  You may
wish to run this with a different 'prefix'

	make install prefix=/opt/tinderbox

It is currently assumed that the bin directory of your installation
will be where the webserver will run the tinderbox cgi's from.  You
can copy the *.cgi files to another directory if this is not the case.


*) set up a cron job to run $prefix/bin/tinder.cgi --daemon-mode 
	every five minutes.
   set up a cron job to run $prefix/bin/tinder.cgi/rmlogs once a day.
     six am is a good time to run this as the machine load is usually light
      and will avoids any day light savings problems.

*) set up the $prefix/bin/processmail* programs to receive the
incoming tinderbox mail.  The process id which receives and process
the mail must be the the same id which runs the tinderbox cron job to
prepare the web pages.  Usually this set up is accomplished by having
the MTA (Sendmail) pass mail for particular accounts into a script.
This can be configued via a global configuration file (Sendmail alias
file) or via a .forward file (each account gets the same user id but a
different home directory, each home directory gets a .forward to cause
incomming mail to be delivered through the correct tinderbox mail
processing program).  

If it is not possible to have mail delivery on your web machine and to
have your web machine deliver specific mail through a program then I
suggest you use fetchmail to simulate this delivery format.  Download
fetchmail (from http://tuxedo.org/~esr/fetchmail) and install it on
your webserver.  Have the mail sent to any pop/imap mail server which
is accessible from the webserver.  Configure fetchmail to gather the
mail from the mail server and pass it through to the correct mail
processing program.  You should keep the polling interval short (30
seconds) as long polling intervals will cause delays in the tinderbox
system and limit how quickly users see the new data.  If the polling
interval is too short then you will overload your pop server with
needless queries.  Fetchmail should run under the same id as the
tinderbox server.  The fetchmail configuration file will look
something like:

	poll mail.provider.net with proto pop3:
               user "tinderbox_builds" there has password "u can't krak this"
               is tinder here and wants mda "$prefix/bin/processmail_builds"




We use the mail address 'tinderbox_builds' for build information
destined for the webserver. Similarly the bug tracking system should
send mail to 'tinderbox_bugs'.


*) If you are using VC_CVS.pm then you will need to put a ~/.cvspass
for tinderbox to use.  Log into the CVS repository yourself, once for
each tree you have defined.  The login command must use the
hostname/modules exactly as you wrote it in VCData.  Then copy your
~/.cvspass into the tinderbox server user id's home directory.  This
must be the REAL home of the Tinderbox daemon, as listed in
/etc/passwd/ and set in the $HOME environmental variable for
tinder.cgi.


*) Setup the build machines to mail their build logs (with tinderbox
variables on the top) to the web server machine.  New builds must not
start earlier then 6 minutes after the last build started.  Each build
machine mails the build log of each build and puts some build data at
the top of the log.  Build information includes whether the build was
a success, which error parsers to use on the log file and what build
this is.  Run 'processmail_builds --help' to learn about how the mail
processing system works and what the mail messages are expected to
look like.  There is an example mail in the test directory called
samplelog.


*) Set up the bug tracking system to send mail to 'tinderbox_bugs' on
the webserver machine whenever a Bug ticket changes state. It is not
interesting to see which tickets are being worked on, so restrict
mailing to changes in ticket state not updates (edit) of a ticket.


*) Check that the time on your webserver, your version control
machine, your bug tracking machine and your build machines are all in
sync.  Check that mail if build mail bounces on any of the above
machines that it will be recieved by someone who can act on it.