import rt 3.2.2

1 files changed, 121 insertions, 83 deletions

diff --git a/rt/README b/rt/README
index 7188f09..9373f69 100755
--- a/rt/README
+++ b/rt/README
@@ -1,8 +1,14 @@
-# BEGIN LICENSE BLOCK
+# {{{ BEGIN BPS TAGGED BLOCK
 # 
-# Copyright (c) 1996-2003 Jesse Vincent <jesse@bestpractical.com>
+# COPYRIGHT:
+#  
+# This software is Copyright (c) 1996-2004 Best Practical Solutions, LLC 
+#                                          <jesse@bestpractical.com>
 # 
-# (Except where explictly superceded by other copyright notices)
+# (Except where explicitly superseded by other copyright notices)
+# 
+# 
+# LICENSE:
 # 
 # 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
@@ -14,14 +20,29 @@
 # 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.
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 # 
 # 
-# END LICENSE BLOCK
-
+# CONTRIBUTION SUBMISSION POLICY:
+# 
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+# 
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+# 
+# }}} END BPS TAGGED 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
@@ -29,30 +50,31 @@ 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.
 
+RT is commercially supported software. To purchase support, training,
+custom development or professional services, please write to
+sales@bestpractical.com. 
 
         Jesse Vincent
         Best Practical Solutions, LLC
-        March 2003
+        June 2004
+
 
 REQUIRED PACKAGES:
 ------------------
 
 o   Perl 5.8.3 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 versions prior to 5.8.3 contain bugs that could result in data
-    corruption. We recommend strongly that you use 5.8.3 or newer.
-
-    Perl 5.6.1 is currently deprecated and will be officially desupported
-    in a future release
+	    Perl versions prior to 5.8.3 contain bugs that could result
+	    in data corruption. We recommend strongly that you use 5.8.3
+	    or newer. RT may function with perl 5.8.0 and later, but
+	    is unsupported in that configuration.
 
 o   A DB backend; MySQL is recommended ( http://www.mysql.com ) 
-        Currently supported:  Mysql 4.0.13 or later. 
+        Currently supported:  Mysql 4.0.13 or later with InnoDB support.
                               Postgres 7.2 or later.
                               Oracle 9iR2.
+        Beta-quality support for Informix and SQLite is also available.
+
 
 o   Apache version 1.3.x or 2.x (http://httpd.apache.org) 
     with mod_perl -- (http://perl.apache.org ) 
@@ -67,23 +89,7 @@ o   Apache version 1.3.x or 2.x (http://httpd.apache.org)
 
         mod_perl 1.x must be build with EVERYTHING=1
 
-        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.
-
-        FreeBSD 4.2+: the package is called sperl, and should
-         install a suidperl that just works 
-
-        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.
-
-
+        RT's FastCGI handler needs to access RT's configuration file.
 
 o    Various and sundry perl modules
 	A tool included with RT takes care of the installation of
@@ -98,9 +104,10 @@ o    Various and sundry perl modules
 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 
+This is a rough guide to installing RT. For more detail, you'll
+want to read a more comprehensive installation guide at:
+
+    http://wiki.bestpractical.com/index.cgi?InstallationGuides
 
 1   Unpack this distribution SOMWHERE OTHER THAN where you want to install RT
 
@@ -113,57 +120,61 @@ http://www.bestpractical.com/rt
         ./configure --help to see the list of options
         ./configure (with the flags you want)
 
-3   Satisfy RT's myriad dependencies. 
+3   Make sure that RT has everything it needs to run:
 
-3.1   Check for compliance:
-        
-   perl sbin/rt-test-dependencies \ 
-                --with-<databasename> --with-<web-environment>
+3.1   Check for missing dependencies:
 
-        databasename is one of: mysql, postgres, oracle
-        web-environment is one of: fastcgi, modperl1, modperl2
+        make testdeps        
 
 3.2   If there are unsatisfied dependencies, install them by hand or run:
 
-        perl sbin/rt-test-dependencies \
-                --with-<databasename> --with-<web-environment> --install
-        
+        make fixdeps
 
 3.3   Check to make sure everything was installed properly:
+        
+        make testdeps
 
-        perl sbin/rt-test-dependencies \
-                --with-<databasename> --with-<web-environment>
+        It might sometimes be necessary to run "make fixdeps" several times
+        to install all necessary perl modules.
 
 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   
                        
                  make initialize-database 
 
-
         If the make fails, type:
                 make dropdb 
         and start over from step 5a
 
-5b  FOR UPGRADING: (Within the RT 3.0.x series)
-
+5b  FOR UPGRADING: (Within the RT 3.x series)
 
         Read through the UPGRADING document included in this distribution.
-        It may contain important instructions for updating your database
+        It may contain important instructions which will help you upgrade
+        RT safely.
 
         As root, type: 
-                make upgrade     (replace "make" with the local name for 
-                                  Make, if you need to)
+                make upgrade    
 
         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 
+
+        You may also need to update RT's database.  To find out, type:
+
+           ls etc/upgrade
+
+        For each item in that directory whose name is greater than
+        your previously installed RT version, run:
+            /opt/rt3/sbin/rt-setup-database --action schema \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action acl \
+                --datadir etc/upgrade/<version>
+            /opt/rt3/sbin/rt-setup-database --action insert \
+                 --datadir etc/upgrade/<version>
+
 
 5c  FOR UPGRADING: (From RT 2.0.x)
 
@@ -193,12 +204,14 @@ http://www.bestpractical.com/rt
 THE WEB INTERFACE
 -----------------
 
-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'.
+RT's web interface is based around HTML::Mason, which works well with
+the mod_perl perl interpreter within Apache httpd and FastCGI
+
+mod_perl
+--------
 
-Apache 
-        You'll need to add a few lines to your httpd.conf telling it about RT:
+To install RT with mod_perl, you'll need to add a few lines to your 
+Apache configuration file telling it about RT:
 
 <VirtualHost your.ip.address>
     ServerName your.rt.server.hostname
@@ -221,11 +234,44 @@ Apache
     </Location>
 </VirtualHost>
 
+FastCGI
+-------
+
+Installation with FastCGI is a little bit more complex and is documented 
+in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
+
+In the most basic configuration, you can set up your webserver to run
+as a user who is a member of the "rt" unix group so that the FastCGI script
+can read RT's configuration file.  It's important to understand the security
+implications of this configuration, which are discussed in the document
+mentioned above.
+
+To install RT with FastCGI, you'll need to add a few lines to your 
+Apache configuration file telling it about RT:
+
+<VirtualHost rt.example.com>
+
+   # Pass through requests to display images
+   Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
+   
+   # Tell FastCGI to put its temporary files somewhere sane.
+   FastCgiIpcDir /tmp
+
+   FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
+
+   AddHandler fastcgi-script fcgi
+   ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
+   
+</VirtualHost>
+
 
 
 SETTING UP THE MAIL GATEWAY 
 ---------------------------
 
+RT can accept incoming email using a simple program run as a "pipe" 
+by your mail server.
+
 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.
@@ -246,14 +292,15 @@ rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url ht
 BUGS
 ----
 
-To report a bug, send email to rt-3.0-bugs@fsck.com.
+To report a bug, send email to rt-bugs@fsck.com.
 
 GETTING HELP
 ------------
 
 If RT is mission-critical for you or if you use it heavily, we recommend that
 you purchase a commercial support contract.  Details on support contracts
-are available at http://www.bestpractical.com.
+are available at http://www.bestpractical.com or by writing to
+sales@bestpractical.com.
 
 If you're interested in having RT extended or customized or would like more
 information about commercial support options, please send email to 
@@ -266,15 +313,15 @@ 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:
 
-         rt-users-request@lists.fsck.com 
+         rt-users-request@lists.bestpractical.com 
 
 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
-rt-devel@lists.fsck.com.  Subscribe to it with instructions similar to
-those above.
+rt-devel@lists.bestpractical.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
@@ -288,15 +335,6 @@ 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.
-
-
-TROUBLESHOOTING
----------------
-
-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 
-versions of RT) or rt-devel@fsck.com (for development versions).
-
-Thanks!