rt/README

   1 # {{{ BEGIN BPS TAGGED BLOCK
   2 #
   3 # COPYRIGHT:
   4 #
   5 # This software is Copyright (c) 1996-2004 Best Practical Solutions, LLC
   6 #                                          <jesse@bestpractical.com>
   7 #
   8 # (Except where explicitly superseded by other copyright notices)
   9 #
  10 #
  11 # LICENSE:
  12 #
  13 # This work is made available to you under the terms of Version 2 of
  14 # the GNU General Public License. A copy of that license should have
  15 # been provided with this software, but in any event can be snarfed
  16 # from www.gnu.org.
  17 #
  18 # This work is distributed in the hope that it will be useful, but
  19 # WITHOUT ANY WARRANTY; without even the implied warranty of
  20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 # General Public License for more details.
  22 #
  23 # You should have received a copy of the GNU General Public License
  24 # along with this program; if not, write to the Free Software
  25 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  26 #
  27 #
  28 # CONTRIBUTION SUBMISSION POLICY:
  29 #
  30 # (The following paragraph is not intended to limit the rights granted
  31 # to you to modify and distribute this software under the terms of
  32 # the GNU General Public License and is only of importance to you if
  33 # you choose to contribute your changes and enhancements to the
  34 # community by submitting them to Best Practical Solutions, LLC.)
  35 #
  36 # By intentionally submitting any modifications, corrections or
  37 # derivatives to this work, or any other work intended for use with
  38 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
  39 # you are the copyright holder for those contributions and you grant
  40 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  41 # royalty-free, perpetual, license to use, copy, create derivative
  42 # works based on those contributions, and sublicense and distribute
  43 # those contributions and any derivatives thereof.
  44 #
  45 # }}} END BPS TAGGED BLOCK
  46 RT is an enterprise-grade issue tracking system. It allows
  47 organizations to keep track of their to-do lists, who is working
  48 on which tasks, what's already been done, and when tasks were
  49 completed. It is available under the terms of version 2 of the GNU
  50 General Public License (GPL), so it doesn't cost anything to set
  51 up and use.
  52
  53 RT is commercially supported software. To purchase support, training,
  54 custom development or professional services, please write to
  55 sales@bestpractical.com.
  56
  57         Jesse Vincent
  58         Best Practical Solutions, LLC
  59         June 2004
  60
  61
  62 REQUIRED PACKAGES:
  63 ------------------
  64
  65 o   Perl 5.8.3 or later (http://www.perl.com).
  66
  67             Perl versions prior to 5.8.3 contain bugs that could result
  68             in data corruption. We recommend strongly that you use 5.8.3
  69             or newer. RT may function with perl 5.8.0 and later, but
  70             is unsupported in that configuration.
  71
  72 o   A DB backend; MySQL is recommended ( http://www.mysql.com )
  73         Currently supported:  Mysql 4.0.13 or later with InnoDB support.
  74                               Postgres 7.2 or later.
  75                               Oracle 9iR2.
  76         Beta-quality support for Informix and SQLite is also available.
  77
  78
  79 o   Apache version 1.3.x or 2.x (http://httpd.apache.org)
  80     with mod_perl -- (http://perl.apache.org )
  81     or a webserver with FastCGI support (www.fastcgi.com)
  82
  83         mod_perl 2.0 isn't quite ready for prime_time just yet;
  84         Best Practical Solutions strongly recommends that sites use
  85         Apache 1.3 or FastCGI.
  86
  87         Compiling mod_perl on Apache 1.3.x as a DSO has been known
  88          to have massive stability problems and is not recommended.
  89
  90         mod_perl 1.x must be build with EVERYTHING=1
  91
  92         RT's FastCGI handler needs to access RT's configuration file.
  93
  94 o    Various and sundry perl modules
  95         A tool included with RT takes care of the installation of
  96         most of these automatically during the install process.
  97
  98         The tool supplied with RT uses Perl's CPAN system
  99         (http://www.cpan.org) to install modules. Some operating
 100         systems package all or some of the modules required and
 101         you may be better off installing the modules that way.
 102
 103
 104 GENERAL INSTALLATION
 105 --------------------
 106
 107 This is a rough guide to installing RT. For more detail, you'll
 108 want to read a more comprehensive installation guide at:
 109
 110     http://wiki.bestpractical.com/index.cgi?InstallationGuides
 111
 112 1   Unpack this distribution SOMWHERE OTHER THAN where you want to install RT
 113
 114         Granted, you've already got it open. To do this cleanly:
 115
 116                 tar xzvf rt.tar.gz -C /tmp
 117
 118 2   Run the "configure" script.
 119
 120         ./configure --help to see the list of options
 121         ./configure (with the flags you want)
 122
 123 3   Make sure that RT has everything it needs to run:
 124
 125 3.1   Check for missing dependencies:
 126
 127         make testdeps
 128
 129 3.2   If there are unsatisfied dependencies, install them by hand or run:
 130
 131         make fixdeps
 132
 133 3.3   Check to make sure everything was installed properly:
 134
 135         make testdeps
 136
 137         It might sometimes be necessary to run "make fixdeps" several times
 138         to install all necessary perl modules.
 139
 140 4   Create a group called 'rt'
 141
 142 5a  FOR A NEW INSTALLATION:
 143
 144         As root, type:
 145                  make install
 146
 147                  make initialize-database
 148
 149         If the make fails, type:
 150                 make dropdb
 151         and start over from step 5a
 152
 153 5b  FOR UPGRADING: (Within the RT 3.x series)
 154
 155         Read through the UPGRADING document included in this distribution.
 156         It may contain important instructions which will help you upgrade
 157         RT safely.
 158
 159         As root, type:
 160                 make upgrade
 161
 162         This will build new binaries, config files and libraries without
 163         overwriting your RT database.
 164
 165         You may also need to update RT's database.  To find out, type:
 166
 167            ls etc/upgrade
 168
 169         For each item in that directory whose name is greater than
 170         your previously installed RT version, run:
 171             /opt/rt3/sbin/rt-setup-database --action schema \
 172                 --datadir etc/upgrade/<version>
 173             /opt/rt3/sbin/rt-setup-database --action acl \
 174                 --datadir etc/upgrade/<version>
 175             /opt/rt3/sbin/rt-setup-database --action insert \
 176                  --datadir etc/upgrade/<version>
 177
 178
 179 5c  FOR UPGRADING: (From RT 2.0.x)
 180
 181     Download the RT2 to RT3 migration tools from:
 182
 183     http://bestpractical.com/pub/rt/devel/rt2-to-rt3.tar.gz
 184
 185     Follow the included instructions.
 186
 187 6   Edit etc/RT_SiteConfig.pm in your RT installation directory, by specifying
 188     any values you need to change from the defaults in etc/RT_Config.pm
 189
 190 7   Configure the email and web gateways, as described below.
 191
 192 8   Stop and start your webserver, so it picks up your configuration changes.
 193
 194     NOTE: root's password for the web interface is "password"
 195     (without the quotes.)  Not changing this is a SECURITY risk
 196
 197 9   Configure RT per the instructions in RT's manual.
 198
 199     Until you do this, RT will not be able to send or receive email,
 200     nor will it be more than marginally functional.  This is not an
 201     optional step.
 202
 203
 204 THE WEB INTERFACE
 205 -----------------
 206
 207 RT's web interface is based around HTML::Mason, which works well with
 208 the mod_perl perl interpreter within Apache httpd and FastCGI
 209
 210 mod_perl
 211 --------
 212
 213 To install RT with mod_perl, you'll need to add a few lines to your
 214 Apache configuration file telling it about RT:
 215
 216 <VirtualHost your.ip.address>
 217     ServerName your.rt.server.hostname
 218     DocumentRoot /opt/rt3/share/html
 219     AddDefaultCharset UTF-8
 220
 221     # these four lines apply to Apache2+mod_perl2 only: {{{
 222     PerlSetVar MasonArgsMethod CGI
 223     PerlModule Apache2 Apache::compat
 224     RewriteEngine On
 225     RewriteRule ^(.*)/$ $1/index.html
 226     # }}}
 227
 228     PerlModule Apache::DBI
 229     PerlRequire /opt/rt3/bin/webmux.pl
 230
 231     <Location />
 232         SetHandler perl-script
 233         PerlHandler RT::Mason
 234     </Location>
 235 </VirtualHost>
 236
 237 FastCGI
 238 -------
 239
 240 Installation with FastCGI is a little bit more complex and is documented
 241 in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
 242
 243 In the most basic configuration, you can set up your webserver to run
 244 as a user who is a member of the "rt" unix group so that the FastCGI script
 245 can read RT's configuration file.  It's important to understand the security
 246 implications of this configuration, which are discussed in the document
 247 mentioned above.
 248
 249 To install RT with FastCGI, you'll need to add a few lines to your
 250 Apache configuration file telling it about RT:
 251
 252 <VirtualHost rt.example.com>
 253
 254    # Pass through requests to display images
 255    Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
 256
 257    # Tell FastCGI to put its temporary files somewhere sane.
 258    FastCgiIpcDir /tmp
 259
 260    FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
 261
 262    AddHandler fastcgi-script fcgi
 263    ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
 264
 265 </VirtualHost>
 266
 267
 268
 269 SETTING UP THE MAIL GATEWAY
 270 ---------------------------
 271
 272 RT can accept incoming email using a simple program run as a "pipe"
 273 by your mail server.
 274
 275 An alias for the initial queue will need to be made in either your
 276 global mail aliases file (if you are using NIS) or locally on your
 277 machine.
 278
 279 Add the following lines to /etc/aliases (or your local equivalent) :
 280
 281 rt:         "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://localhost/"
 282 rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://localhost/"
 283                                             |                |             |
 284                             <queue-name>----/                |             |
 285                                                              |             |
 286                <correspond or comment depending on whether   |             |
 287                the mail should be resent to the requestor>---/             |
 288                                                                            |
 289                                             <URL for RT's web interface>---/
 290
 291
 292 BUGS
 293 ----
 294
 295 To report a bug, send email to rt-bugs@fsck.com.
 296
 297 GETTING HELP
 298 ------------
 299
 300 If RT is mission-critical for you or if you use it heavily, we recommend that
 301 you purchase a commercial support contract.  Details on support contracts
 302 are available at http://www.bestpractical.com or by writing to
 303 sales@bestpractical.com.
 304
 305 If you're interested in having RT extended or customized or would like more
 306 information about commercial support options, please send email to
 307 <sales@bestpractical.com> to discuss rates and availability.
 308
 309
 310 RT-USERS MAILINGLIST
 311 --------------------
 312
 313 To keep up to date on the latest RT tips, techniques and extensions,
 314 you probably want to join the rt-users mailing list.  Send a message to:
 315
 316          rt-users-request@lists.bestpractical.com
 317
 318 With the body of the message consisting of only the word:
 319
 320         subscribe
 321
 322 If you're interested in hacking on RT, you'll want to subscribe to
 323 rt-devel@lists.bestpractical.com.  Subscribe to it with instructions
 324 similar to those above.
 325
 326 Address questions about the stable release to the rt-users list, and
 327 questions about the development version to the rt-devel list.  If you feel
 328 your questions are best not asked publicly, send them personally to
 329 <jesse@bestpractical.com>.
 330
 331
 332 RT WEBSITE
 333 ----------
 334
 335 For current information about RT, check out the RT website at
 336         http://www.bestpractical.com/
 337
 338
 339 You'll find screenshots, a pointer to the current version of RT, contributed
 340 patches, and lots of other great stuff.