rt/README

   1 # BEGIN LICENSE BLOCK
   2 #
   3 # Copyright (c) 1996-2003 Jesse Vincent <jesse@bestpractical.com>
   4 #
   5 # (Except where explictly superceded by other copyright notices)
   6 #
   7 # This work is made available to you under the terms of Version 2 of
   8 # the GNU General Public License. A copy of that license should have
   9 # been provided with this software, but in any event can be snarfed
  10 # from www.gnu.org.
  11 #
  12 # This work is distributed in the hope that it will be useful, but
  13 # WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 # General Public License for more details.
  16 #
  17 # Unless otherwise specified, all modifications, corrections or
  18 # extensions to this work which alter its source code become the
  19 # property of Best Practical Solutions, LLC when submitted for
  20 # inclusion in the work.
  21 #
  22 #
  23 # END LICENSE BLOCK
  24 RT is an enterprise-grade issue tracking system. It allows
  25 organizations to keep track of their to-do lists, who is working
  26 on which tasks, what's already been done, and when tasks were
  27 completed. It is available under the terms of version 2 of the GNU
  28 General Public License (GPL), so it doesn't cost anything to set
  29 up and use.
  30
  31
  32         Jesse Vincent
  33         Best Practical Solutions, LLC
  34         March 2003
  35
  36 REQUIRED PACKAGES:
  37 ------------------
  38
  39 o   Perl 5.8.0 or later (http://www.perl.com).
  40
  41         (If you intend to use the FastCGI or SpeedyCGI support, you
  42          need to make sure that perl has been built with support for
  43          setgid perl scripts.)`
  44
  45     Perl 5.6.1 is currently deprecated and will be officially desupported
  46     in a future release
  47
  48 o   A DB backend; MySQL is recommended ( http://www.mysql.com )
  49         Currently supported:  Mysql 4.0.13 or later.
  50                               Postgres 7.2 or later.
  51
  52                               Mysql 3.23.46 or newer with support for InnoDB
  53                               is currently deprecated and will be officially
  54                               desupported in a future release.
  55
  56 o   Apache version 1.3.x or 2.x (http://httpd.apache.org)
  57     with mod_perl -- (http://perl.apache.org )
  58     or a webserver with FastCGI support (www.fastcgi.com)
  59
  60         mod_perl 2.0 isn't quite ready for prime_time just yet;
  61         Best Practical Solutions strongly recommends that sites use
  62         Apache 1.3 or FastCGI.
  63
  64         Compiling mod_perl on Apache 1.3.x as a DSO has been known
  65          to have massive stability problems and is not recommended.
  66
  67         mod_perl 1.x must be build with EVERYTHING=1
  68
  69         RT's FastCGI handler runs setgid to the 'rt' group to
  70         protect RT's database password.  You may need to install
  71         a special  "suidperl" package or reconfigure your perl
  72         setup to support "setuid scripts" if you intend to use RT
  73         with FastCGI.
  74
  75         Debian GNU/* 3.0+: the package which installs suidperl is
  76          called perl-suid, and should work without any tweaking.
  77
  78         FreeBSD 4.2+: the package is called sperl, and should
  79          install a suidperl that just works
  80
  81         Conectiva Linux 6.0+: suidperl is installed by default when
  82          perl is installed, but the program /bin/suidperl is not setuid.
  83          You must use chmod to make it setuid.
  84
  85
  86
  87 o    Various and sundry perl modules
  88         A tool included with RT takes care of the installation of
  89         most of these automatically during the install process.
  90
  91         The tool supplied with RT uses Perl's CPAN system
  92         (http://www.cpan.org) to install modules. Some operating
  93         systems package all or some of the modules required and
  94         you may be better off installing the modules that way.
  95
  96
  97 GENERAL INSTALLATION
  98 --------------------
  99
 100 This is a rough guide to installing RT. For more detail, you'll want
 101 to read 'Chapter 2: Installing' in RT's manual, available at
 102 http://www.bestpractical.com/rt
 103
 104 1   Unpack this distribution SOMWHERE OTHER THAN where you want to install RT
 105
 106         Granted, you've already got it open. To do this cleanly:
 107
 108                 tar xzvf rt.tar.gz -C /tmp
 109
 110 2   Run the "configure" script.
 111
 112         ./configure --help to see the list of options
 113         ./configure (with the flags you want)
 114
 115 3   Satisfy RT's myriad dependencies.
 116
 117 3.1   Check for compliance:
 118
 119    perl sbin/rt-test-dependencies \
 120                 --with-<databasename> --with-<web-environment>
 121
 122         databasename is one of: mysql, postgres
 123         web-environment is one of: fastcgi, modperl1, modperl2
 124
 125 3.2   If there are unsatisfied dependencies, install them by hand or run:
 126
 127         perl sbin/rt-test-dependencies \
 128                 --with-<databasename> --with-<web-environment> --install
 129
 130
 131 3.3   Check to make sure everything was installed properly:
 132
 133         perl sbin/rt-test-dependencies \
 134                 --with-<databasename> --with-<web-environment>
 135
 136 4   Create a group called 'rt'
 137
 138 5a  FOR A NEW INSTALLATION:
 139
 140         As root, type:
 141                  make install        (replace "make" with the local name for
 142                                  Make, if you need to)
 143
 144
 145                  make initialize-database
 146
 147
 148         If the make fails, type:
 149                 make dropdb
 150         and start over from step 5a
 151
 152 5b  FOR UPGRADING: (Within the RT 3.0.x series)
 153
 154         As root, type:
 155                 make upgrade     (replace "make" with the local name for
 156                                   Make, if you need to)
 157
 158         This will build new binaries, config files and libraries without
 159         overwriting your RT database.
 160
 161         It may then instruct you to update your RT system database objects
 162
 163 6   Edit etc/RT_SiteConfig.pm in your RT installation directory, by specifying
 164     any values you need to change from the defaults in etc/RT_Config.pm
 165
 166 7   Configure the email and web gateways, as described below.
 167
 168 8   Stop and start your webserver, so it picks up your configuration changes.
 169
 170     NOTE: root's password for the web interface is "password"
 171     (without the quotes.)  Not changing this is a SECURITY risk
 172
 173 9   Configure RT per the instructions in RT's manual.
 174
 175     Until you do this, RT will not be able to send or receive email,
 176     nor will it be more than marginally functional.  This is not an
 177     optional step.
 178
 179
 180 THE WEB INTERFACE
 181 -----------------
 182
 183 RT's web interface is based around HTML::Mason, which works best with the mod_perl
 184 perl interpreter within Apache httpd.  Alternatively, support for the FastCGI
 185 (and plain CGI) interface is also provided as 'bin/mason_handler.fcgi'.
 186
 187 Apache
 188         You'll need to add a few lines to your httpd.conf telling it about RT:
 189
 190 <VirtualHost your.ip.address>
 191     ServerName your.rt.server.hostname
 192     DocumentRoot /opt/rt3/share/html
 193     AddDefaultCharset UTF-8
 194
 195     # this line applies to Apache2+mod_perl2 only
 196     PerlModule Apache2 Apache::compat
 197
 198     PerlModule Apache::DBI
 199     PerlRequire /opt/rt3/bin/webmux.pl
 200
 201     # this section applies to Apache 1 only
 202     <Location />
 203         SetHandler perl-script
 204         PerlHandler RT::Mason
 205     </Location>
 206
 207     # this section applies to Apache2+mod_perl2 only
 208     <FilesMatch "\.html$">
 209         SetHandler perl-script
 210         PerlHandler RT::Mason
 211     </FilesMatch>
 212     <LocationMatch "/Attachment/">
 213         SetHandler perl-script
 214         PerlHandler RT::Mason
 215     </LocationMatch>
 216     <LocationMatch "/REST/">
 217         SetHandler perl-script
 218         PerlHandler RT::Mason
 219     </LocationMatch>
 220 </VirtualHost>
 221
 222
 223
 224 SETTING UP THE MAIL GATEWAY
 225 ---------------------------
 226
 227 An alias for the initial queue will need to be made in either your
 228 global mail aliases file (if you are using NIS) or locally on your
 229 machine.
 230
 231 Add the following lines to /etc/aliases (or your local equivalent) :
 232
 233 rt:         "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://localhost/"
 234 rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://localhost/"
 235                                             |                |             |
 236                             <queue-name>----/                |             |
 237                                                              |             |
 238                <correspond or comment depending on whether   |             |
 239                the mail should be resent to the requestor>---/             |
 240                                                                            |
 241                                             <URL for RT's web interface>---/
 242
 243
 244 BUGS
 245 ----
 246
 247 To report a bug, send email to rt-3.0-bugs@fsck.com.
 248
 249 GETTING HELP
 250 ------------
 251
 252 If RT is mission-critical for you or if you use it heavily, we recommend that
 253 you purchase a commercial support contract.  Details on support contracts
 254 are available at http://www.bestpractical.com.
 255
 256 If you're interested in having RT extended or customized or would like more
 257 information about commercial support options, please send email to
 258 <sales@bestpractical.com> to discuss rates and availability.
 259
 260
 261 RT-USERS MAILINGLIST
 262 --------------------
 263
 264 To keep up to date on the latest RT tips, techniques and extensions,
 265 you probably want to join the rt-users mailing list.  Send a message to:
 266
 267          rt-users-request@lists.fsck.com
 268
 269 With the body of the message consisting of only the word:
 270
 271         subscribe
 272
 273 If you're interested in hacking on RT, you'll want to subscribe to
 274 rt-devel@lists.fsck.com.  Subscribe to it with instructions similar to
 275 those above.
 276
 277 Address questions about the stable release to the rt-users list, and
 278 questions about the development version to the rt-devel list.  If you feel
 279 your questions are best not asked publicly, send them personally to
 280 <jesse@bestpractical.com>.
 281
 282
 283 RT WEBSITE
 284 ----------
 285
 286 For current information about RT, check out the RT website at
 287         http://www.bestpractical.com/
 288
 289 You'll find screenshots, a pointer to the current version of RT, contributed
 290 patches, and lots of other great stuff.
 291
 292
 293 TROUBLESHOOTING
 294 ---------------
 295
 296 If the solution to the problem you're running into isn't obvious and you've
 297 checked the FAQ, feel free to send mail to rt-users@fsck.com (for released
 298 versions of RT) or rt-devel@fsck.com (for development versions).
 299
 300 Thanks!