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