X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=rt%2FREADME;h=d16100c5f4d10d5baf24fa9d24258004c3ca348d;hb=256a89fc37c3d6a16518d833adef3a8bacaf3f5d;hp=7c5e4d47ad8abacf3187f1bcbd09ddaee00985c9;hpb=ded0451e9582df33cae6099a2fb72b4ea25076cf;p=freeside.git diff --git a/rt/README b/rt/README index 7c5e4d47a..d16100c5f 100755 --- a/rt/README +++ b/rt/README @@ -1,167 +1,139 @@ -# BEGIN LICENSE BLOCK -# -# Copyright (c) 1996-2003 Jesse Vincent -# -# (Except where explictly superceded by other copyright notices) -# -# This work is made available to you under the terms of Version 2 of -# the GNU General Public License. A copy of that license should have -# been provided with this software, but in any event can be snarfed -# from www.gnu.org. -# -# This work is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# Unless otherwise specified, all modifications, corrections or -# extensions to this work which alter its source code become the -# property of Best Practical Solutions, LLC when submitted for -# inclusion in the work. -# -# -# END LICENSE BLOCK -RT is an enterprise-grade issue tracking system. It allows -organizations to keep track of their to-do lists, who is working -on which tasks, what's already been done, and when tasks were -completed. It is available under the terms of version 2 of the GNU -General Public License (GPL), so it doesn't cost anything to set -up and use. +$Header: /home/cvs/cvsroot/freeside/rt/README,v 1.1 2002-08-12 06:17:06 ivan Exp $ +RT is (c) 1996-2002 by Jesse Vincent +RT is licensed to you under the terms of version 2 of the GNU General +Public License. - Jesse Vincent - Best Practical Solutions, LLC - March 2003 - -REQUIRED PACKAGES: ------------------- - -o Perl 5.8.0 or later (http://www.perl.com). - - (If you intend to use the FastCGI or SpeedyCGI support, you - need to make sure that perl has been built with support for - setgid perl scripts.)` - - Perl 5.6.1 is currently deprecated and will be officially desupported - in a future release - -o A DB backend; MySQL is recommended ( http://www.mysql.com ) - Currently supported: Mysql 4.0.13 or later. - Postgres 7.2 or later. - - Mysql 3.23.46 or newer with support for InnoDB - is currently deprecated and will be officially - desupported in a future release. - -o Apache version 1.3.x or 2.x (http://httpd.apache.org) - with mod_perl -- (http://perl.apache.org ) - or a webserver with FastCGI support (www.fastcgi.com) +If you don't have a copy of the GPL, you've been living in a cave, +but one should be included in this distribution. - mod_perl 2.0 isn't quite ready for prime_time just yet; - Best Practical Solutions strongly recommends that sites use - Apache 1.3 or FastCGI. - Compiling mod_perl on Apache 1.3.x as a DSO has been known - to have massive stability problems and is not recommended. +INSTALLATION INSTRUCTIONS +------------------------- - mod_perl 1.x must be build with EVERYTHING=1 +These instructions are a summary of those at http://www.fsck.com/rtfm/ +The docs on the web at www.fsck.com/rtfm/ are likely to be more up to +date and complete than this document. You should consult them before +proceeding. - RT's FastCGI handler runs setgid to the 'rt' group to - protect RT's database password. You may need to install - a special "suidperl" package or reconfigure your perl - setup to support "setuid scripts" if you intend to use RT - with FastCGI. - - Debian GNU/* 3.0+: the package which installs suidperl is - called perl-suid, and should work without any tweaking. +REQUIRED PACKAGES: +------------------ - FreeBSD 4.2+: the package is called sperl, and should - install a suidperl that just works +o Perl5.005_03 or later with support for setgid perl scripts + RT's command line and mail gateway tools run setgid to the 'rt' group + to protect RT's database password. You may need to install a special + "suidperl" package or reconfigure your perl setup to support + "setuid scripts". - Conectiva Linux 6.0+: suidperl is installed by default when - perl is installed, but the program /bin/suidperl is not setuid. - You must use chmod to make it setuid. +o A DB backend; MySQL is recommended ( http://www.mysql.com ) + Currently supported: Mysql 3.23.38 or newer. + (Some older releases had crippling SQL bugs) + Postgres 7.1 or newer. +o Apache + mod_perl -- ( http://perl.apache.org) + or A webserver with FastCGI support (www.fastcgi.com) + If you compile mod_perl as a DSO, you're on your own. It's known + to have massive stability problems. + mod_perl must be build with EVERYTHING=1 o Various and sundry perl modules - A tool included with RT takes care of the installation of - most of these automatically during the install process. - - The tool supplied with RT uses Perl's CPAN system - (http://www.cpan.org) to install modules. Some operating - systems package all or some of the modules required and - you may be better off installing the modules that way. + RT takes care of the installation of most of these automatically + during the "make testdeps" and "make fixdeps" stages below GENERAL INSTALLATION -------------------- -This is a rough guide to installing RT. For more detail, you'll want -to read 'Chapter 2: Installing' in RT's manual, available at -http://www.bestpractical.com/rt - 1 Unpack this distribution SOMWHERE OTHER THAN where you want to install RT Granted, you've already got it open. To do this cleanly: - tar xzvf rt.tar.gz -C /tmp + tar xzvf rt.tar.gz -C /tmp -2 Run the "configure" script. +2 Check over /tmp/rt/Makefile - ./configure --help to see the list of options - ./configure (with the flags you want) + There are many variables you NEED to customize for your site. + Even if you are just upgrading, you must set ALL variables. -3 Satisfy RT's myriad dependencies. +3 Satisfy RT's myriad dependencies. There's a perl script in rt/tools + called testdeps that uses CPAN to automate all of this. 3.1 Check for compliance: - - perl sbin/rt-test-dependencies \ - --with- --with- - - databasename is one of: mysql, postgres - web-environment is one of: fastcgi, modperl1, modperl2 + make testdeps -3.2 If there are unsatisfied dependencies, install them by hand or run: +3.2 If there are unsatisfied dependencies, install them by hand or run + make fixdeps + + (You may need to install Apache::Session and Apache::DBI by hand. - perl sbin/rt-test-dependencies \ - --with- --with- --install - + You might need to install Msql-Mysql-Modules by hand. + perl -MCPAN -e'install DBD::mysql::Install' should do it for you. + ) 3.3 Check to make sure everything was installed properly: - - perl sbin/rt-test-dependencies \ - --with- --with- + make testdeps 4 Create a group called 'rt' 5a FOR A NEW INSTALLATION: As root, type: - make install (replace "make" with the local name for - Make, if you need to) + make install (replace "make" with the local name for + Make, if you need to) - - make initialize-database + If the make fails, type: + make dropdb + and start over from step 5a +5b FOR UPGRADING: (Within the RT 2.0.x series) - If the make fails, type: - make dropdb - and start over from step 5a + Make a backup of /path/to/rt/etc/config.pm + + As root, type: + make upgrade (replace "make" with the local name for + Make, if you need to) -5b FOR UPGRADING: (Within the RT 3.0.x series) + This will build new binaries, config files and libraries without + overwriting your RT database. - As root, type: - make upgrade (replace "make" with the local name for - Make, if you need to) + WARNING: This WILL clobber your existing configuration file! + + The install process will then instruct you to update your RT system + database objects by running rt/etc/insertdata where + is the version of RT you're upgrading from. - This will build new binaries, config files and libraries without - overwriting your RT database. - It may then instruct you to update your RT system database objects + +5c FOR UPGRADING (From 1.0.x): + + Follow the instructions for installing RT 2.0. -6 Edit etc/RT_SiteConfig.pm in your RT installation directory, by specifying - any values you need to change from the defaults in etc/RT_Config.pm + Once you have installed RT 2.0, download import-1.0-to-2.0 + from http://www.fsck.com/pub/rt/contrib/2.0/rt-addons + + Edit the configuration defaults in import-1.0-to-2.0 + + If you don't set $DEFAULTQUEUE to the name of one of your + RT 1.0 queues, THE IMPORT WILL FAIL. + + perl ./import-1.0-to-2.0 + + The import tool will do its thing. If you're using postgres, you'll + need to execute the following SQL statement within your RT2 database: + + select setval('tickets_id_seq', (select max(id) from tickets)); + + It imports: + Queues, Areas, Users, Acls, Mailing Rules, Queue Members, + Tickets and Transactions. + + It DOES NOT IMPORT: + Attachments removed by stripmime or Templates. + +6 Edit etc/config.pm in your RT installation directory. In many + cases sensible defaults have been included. In others, you MUST + supply a value. 7 Configure the email and web gateways, as described below. @@ -170,81 +142,97 @@ http://www.bestpractical.com/rt NOTE: root's password for the web interface is "password" (without the quotes.) Not changing this is a SECURITY risk -9 Configure RT per the instructions in RT's manual. +9 Configure RT per the instructions at http://www.fsck.com/rtfm/ - Until you do this, RT will not be able to send or receive email, + Until you do this, RT will not be able to send or recieve email, nor will it be more than marginally functional. This is not an optional step. -THE WEB INTERFACE ------------------ +SETTING UP THE MAIL GATEWAY +--------------------------- -RT's web interface is based around HTML::Mason, which works best with the mod_perl -perl interpreter within Apache httpd. Alternatively, support for the FastCGI -(and plain CGI) interface is also provided as 'bin/mason_handler.fcgi'. +An alias for the initial queue will need to be made in either your +global mail aliases file (if you are using NIS) or locally on your +machine. + +Add the following lines to /etc/aliases (or your local equivalent) : + +rt: "|/path/to/rt2/bin/rt-mailgate --queue general --action correspond" +rt-comment: "|/path/to/rt2/bin/rt-mailgate --queue general --action comment" + | | + ----/ | + | + ---/ + + + +THE WEB UI +---------- + +RT's web ui is based around HTML::Mason, which works well with the mod_perl +perl interpreter within Apache httpd as well as with a webserver which +supports FastCGI. (Instructions for configuring RT for use with FastCGI +are available at http://www.fsck.com/rtfm/ ) Apache - You'll need to add a few lines to your httpd.conf telling it about RT: + RT Uses HTML::Mason. You'll need to add a few lines to your + httpd.conf telling it to use rt's web ui. If you have mod-perl + (you should, the perl scripts will go quite a bit faster around with + it), you can do something like this: + - ServerName your.rt.server.hostname - DocumentRoot /opt/rt3/share/html - AddDefaultCharset UTF-8 - - # this line applies to Apache2+mod_perl2 only - PerlModule Apache2 Apache::compat - - PerlModule Apache::DBI - PerlRequire /opt/rt3/bin/webmux.pl - - # this section applies to Apache 1 only - - SetHandler perl-script - PerlHandler RT::Mason - - - # this section applies to Apache2+mod_perl2 only - - SetHandler perl-script - PerlHandler RT::Mason - - - SetHandler perl-script - PerlHandler RT::Mason - - - SetHandler perl-script - PerlHandler RT::Mason - +DocumentRoot /path/to/rt2/WebRT/html +ServerName your.rt.server.hostname +PerlModule Apache::DBI +PerlFreshRestart On +PerlRequire /path/to/rt2/bin/webmux.pl + + SetHandler perl-script + PerlHandler RT::Mason + +Additionally, you should set up a cron job to remove stale session data. +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + WARNING: Don't install this cron job or run this find command if your + MASON_SESSION_PATH (known in config.pm as $MasonSessionDir) + points to a directory that could EVER contain any file that's not + a Apache::Session datafile. +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -SETTING UP THE MAIL GATEWAY ---------------------------- +# Every hour, nuke session files and lockfiles that haven't been +# touched in 10 hours -An alias for the initial queue will need to be made in either your -global mail aliases file (if you are using NIS) or locally on your -machine. - -Add the following lines to /etc/aliases (or your local equivalent) : +0 * * * * find /path/to/rt2/WebRT/sessiondata -type f -amin +600 -exec rm {} \; -rt: "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://localhost/" -rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://localhost/" - | | | - ----/ | | - | | - ---/ | - | - ---/ + +THE CLI +------- + Binaries for the CLI are located in rt/bin + You've got: + + "rt" (manipulate or display requests) + "rtadmin" (modify queues, users and acls) + + Both of these programs take --help as an option. BUGS ---- -To report a bug, send email to rt-3.0-bugs@fsck.com. +Known issues with releases of RT2 are listed at +. This includes every bug known +to exist in each release of RT. (When prompted, login as guest/guest) + +To find out more about currently open bugs, check out the live +Buglist at . +(When prompted, login as guest/guest) + +To report a bug, send an email to rt-2.0-bugs@fsck.com. GETTING HELP ------------ @@ -261,8 +249,8 @@ information about commercial support options, please send email to RT-USERS MAILINGLIST -------------------- -To keep up to date on the latest RT tips, techniques and extensions, -you probably want to join the rt-users mailing list. Send a message to: +To keep up to date on the latest RT tips, techniques and extections, +you probably want to join the rt-users mailinglist. Send a message to: rt-users-request@lists.fsck.com @@ -270,31 +258,79 @@ With the body of the message consisting of only the word: subscribe -If you're interested in hacking on RT, you'll want to subscribe to +If you're interested in hacking on rt, you'll want to subscribe to rt-devel@lists.fsck.com. Subscribe to it with instructions similar to those above. Address questions about the stable release to the rt-users list, and questions about the development version to the rt-devel list. If you feel -your questions are best not asked publicly, send them personally to +your questions are best not asked publically, send them personally to . +If you want to be informed of every commit to the CVS repository, +subscribe to rt-commit@fsck.com using similar instructions to those above. + RT WEBSITE ---------- For current information about RT, check out the RT website at - http://www.bestpractical.com/ - -You'll find screenshots, a pointer to the current version of RT, contributed -patches, and lots of other great stuff. +http://www.bestpractical.com/rt You'll find screenshots, a pointer +to the current version of rt, contributed patches and lots of other great +stuff. TROUBLESHOOTING --------------- +All errors will be appended to a logfile, which lives in /tmp/rt.log.* unless +you've reconfigured it. Check etc/config.pm for details. + If the solution to the problem you're running into isn't obvious and you've -checked the FAQ, feel free to send mail to rt-users@fsck.com (for released +checked the FAQ, feel free to send mail to rt-users@fsck.com (for release versions of RT) or rt-devel@fsck.com (for development versions). +GIVING SOMETHING BACK +--------------------- + +RT is free software. You are not obligated to pay for it. You should be +aware, however, that bestpractical.com's sole source of revenue is commercial +work related to RT. If you are able, either a contract to extend RT in some +way that would be useful to your organization, a financial contribution, or +even something off the author's amazon wishlist + ( http://www.amazon.com/exec/obidos/wishlist/2GMHUDAFBT2XR/ ) +would be much appreciated. + Thanks! + + +CREDITS +------- + +A lot of people are responsible for making RT a better program. Many +thanks to Lauren Burka, who originally tasked me with writing this beast. +She forced me to use a database backend. I've thanked her for it every +day since. Rich West rewrote this readme and did some UI hacking. Adam +Hirsch, Kit Kraysha, Robin Garner, Jens Glaser, John Adams, Trey Belew, +Sean Dague, Nathan Mehl, Kee Hinckley, Rich West, Dale Bewley, Serge Zhuk, +John Lengeling, Elmar Knipp, Gerald Abshez, Dave Hull, Dave Schenet, +Dave Walton, Jan Okrouhly, Tobias Brox, Lamont Lucas, Charlie Brady, +Robin Shostack, Eric Mumpower, Jerrod Wiesman, Adam Hammer, Ivan Kohler, Alex +Pilosov, Mary Alderdice, Deborah Kaplan, Jens von Bülow, Tristan Horn, +Lee Ann Goldstein, Karel P Kerezman, Feargal Reilly, Christian Steger, +Christian Kurz, JD Falk, Arthur de Jong, Ben Carter, Mark Vevers +and many others +have all contributed bug reports, code or ideas that have helped RT along. + +Arepa, Inc, Utopia Inc, Wesleyan University and The Leftbank Operation +have paid me to maintain RT and release it to the public. Without their +support RT would not exist. + +If I've left you out, please drop me a line ....it wasn't intentional. + + + Enjoy + + Jesse Vincent + + Best Practical Solutions, LLC