rt/README

   1 RT is an enterprise-grade issue tracking system. It allows organizations
   2 to keep track of what needs to get done, who is working on which tasks,
   3 what's already been done, and when tasks were (or weren't) completed.
   4
   5 RT doesn't cost anything to use, no matter how much you use it; it
   6 is freely available under the terms of Version 2 of the GNU General
   7 Public License.
   8
   9 RT is commercially-supported software. To purchase support, training,
  10 custom development, or professional services, please get in touch with
  11 us at sales@bestpractical.com.
  12
  13      Jesse Vincent
  14      Best Practical Solutions, LLC
  15      March, 2005
  16
  17
  18 REQUIRED PACKAGES
  19 -----------------
  20
  21 o   Perl 5.8.3 or later (http://www.perl.org).
  22
  23         Perl versions prior to 5.8.3 contain bugs that could result
  24         in data corruption. RT won't start on older versions.
  25
  26 o   A supported SQL database
  27
  28         Currently supported:  Mysql 4.0.13 or later with InnoDB support.
  29                               Postgres 7.2 or later.
  30                               Oracle 9iR2 or later.
  31                               SQLite 3.0. (Not recommended for production)
  32
  33 o   Apache version 1.3.x or 2.x (http://httpd.apache.org)
  34         with mod_perl -- (http://perl.apache.org )
  35         or with FastCGI -- (www.fastcgi.com)
  36         or other webserver with FastCGI support
  37
  38         RT's FastCGI handler needs to access RT's configuration file.
  39
  40 o   Various and sundry perl modules
  41         A tool included with RT takes care of the installation of
  42         most of these automatically during the install process.
  43
  44         The tool supplied with RT uses Perl's CPAN system
  45         (http://www.cpan.org) to install modules. Some operating
  46         systems package all or some of the modules required, and
  47         you may be better off installing the modules that way.
  48
  49
  50 GENERAL INSTALLATION
  51 --------------------
  52
  53 This is a rough guide to installing RT. For more detail, you'll
  54 want to read a more comprehensive installation guide at:
  55
  56     http://wiki.bestpractical.com/index.cgi?InstallationGuides
  57
  58 1   Unpack this distribution other than where you want to install RT
  59
  60      To do this cleanly, run the following command:
  61
  62        tar xzvf rt.tar.gz -C /tmp
  63
  64 2   Run the "configure" script.
  65
  66        ./configure --help to see the list of options
  67        ./configure (with the flags you want)
  68
  69     RT defaults to installing in /opt/rt3 with MySQL as its database. It
  70     tries to guess which of www-data, www, apache or nobody your webserver
  71     will run as, but you can override that behavior.  Note that the
  72     default install directory in /opt/rt3 does not work under SELinux's
  73     default configuration.
  74
  75     If you're upgrading RT then it worth to read UPGRADING document at this
  76     moment. Some extension you're using may have been integrated into
  77     core. It's recommended to use new clean directory when you're
  78     upgrading to new major release (for example from 3.6.x to 3.8.x).
  79
  80 3   Make sure that RT has everything it needs to run.
  81
  82     Check for missing dependencies by running:
  83
  84        make testdeps
  85
  86 4   If the script reports any missing dependencies, install them by hand
  87     or run the following command as a user who has permission to install perl
  88     modules on your system:
  89
  90      make fixdeps
  91
  92     Some modules require user input or environment variables to install correctly,
  93     so it may be necessary to install them manually.
  94
  95 5   Check to make sure everything was installed properly.
  96
  97        make testdeps
  98
  99      It might sometimes be necessary to run "make fixdeps" several times
 100      to install all necessary perl modules.
 101
 102 6   If this is a new installation:
 103
 104      As a user with permission to install RT in your chosen directory, type:
 105
 106        make install
 107
 108      Set up etc/RT_SiteConfig.pm in your RT installation directory.
 109      You'll need to add any values you need to change from the defaults
 110      in etc/RT_Config.pm
 111
 112      As a user with permission to read RT's configuration file, type:
 113
 114        make initialize-database
 115
 116      If the make fails, type:
 117
 118        make dropdb
 119
 120      and start over from step 6
 121
 122 7   If you're upgrading from RT 3.0 or newer:
 123
 124      Read through the UPGRADING document included in this distribution. If
 125      you're using MySQL, read through UPGRADING.mysql as well.
 126
 127      It includes special upgrade instructions that will help you get this
 128      new version of RT up and running smoothly.
 129
 130      As a user with permission to install RT in your chosen installation
 131      directory, type:
 132
 133        make upgrade
 134
 135      This will install new binaries, config files and libraries without
 136      overwriting your RT database.
 137
 138      Update etc/RT_SiteConfig.pm in your RT installation directory.
 139      You'll need to add any new values you need to change from the defaults
 140      in etc/RT_Config.pm
 141
 142      You may also need to update RT's database.  You can do this with
 143      the rt-setup-database tool.  Replace root with the name of the dba
 144      user on your database (root is the default for MySQL).
 145
 146      You will be prompted for your previous version of RT (such as 3.6.4)
 147      so that we can calculate which database updates to apply
 148
 149      You should back up your database before running this command.
 150
 151        /opt/rt3/sbin/rt-setup-database --dba root --prompt-for-dba-password --action upgrade
 152
 153      Clear mason cache dir:
 154
 155        rm -fr /opt/rt3/var/mason_data/obj
 156
 157      Stop and start web-server.
 158
 159
 160 8  If you're upgrading from RT 2.0:
 161
 162     Use the RT::Extension::RT2toRT3 module to upgrade to the current RT
 163     release.  You can download it from CPAN here:
 164     http://search.cpan.org/dist/RT-Extension-RT2toRT3/
 165
 166 9   Configure the email and web gateways, as described below.
 167
 168     NOTE: root's password for the web interface is "password"
 169     (without the quotes).  Not changing this is a SECURITY risk!
 170
 171 10  Set up automated recurring tasks (cronjobs):
 172
 173     To generate email digest messages, you must arrange for the provided
 174     utility to be run once daily, and once weekly. You may also want to
 175     arrange for the rt-email-dashboards utility to be run hourly.
 176     For example, if your task scheduler is cron, you can configure it as
 177     follows:
 178
 179         crontab -e    # as the RT administrator (probably root)
 180         # insert the following lines:
 181         0 0 * * * /opt/rt3/sbin/rt-email-digest -m daily
 182         0 0 * * 0 /opt/rt3/sbin/rt-email-digest -m weekly
 183         0 * * * * /opt/rt3/sbin/rt-email-dashboards
 184
 185
 186 11   Set up users, groups, queues, scrips and access control.
 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
 194
 195 SETTING UP THE WEB INTERFACE
 196 ----------------------------
 197
 198 RT's web interface is based around HTML::Mason, which works well with
 199 the mod_perl perl interpreter within Apache httpd and FastCGI.
 200
 201 Once you've set up the web interface, consider setting up automatic
 202 logout for inactive sessions. For more information about how to do that,
 203 run
 204     perldoc /path/to/rt/sbin/rt-clean-sessions
 205
 206
 207 mod_perl 1.xx
 208 -------------
 209
 210 WARNING: mod_perl 1.99_xx is not supported.
 211
 212 See below configuration instructions for mod_perl 2.x
 213
 214 To install RT with mod_perl 1.x, you'll need to install the
 215 apache database connection cache. To make sure it's installed, run
 216 the following command:
 217
 218     perl -MCPAN -e'install "Apache::DBI"'
 219
 220 Next, add a few lines to your Apache 1.3.xx configuration file, so that
 221 it knows where to find RT:
 222
 223 <VirtualHost your.ip.address>
 224     ServerName your.rt.server.hostname
 225
 226     DocumentRoot /opt/rt3/share/html
 227     AddDefaultCharset UTF-8
 228
 229     # optional apache logs for RT
 230     # ErrorLog /opt/rt3/var/log/apache.error
 231     # TransferLog /opt/rt3/var/log/apache.access
 232
 233     PerlModule Apache::DBI
 234     PerlRequire /opt/rt3/bin/webmux.pl
 235
 236     <Location /NoAuth/images>
 237         SetHandler default
 238     </Location>
 239     <Location />
 240         SetHandler perl-script
 241         PerlHandler RT::Mason
 242     </Location>
 243 </VirtualHost>
 244
 245 mod_perl 2.xx
 246 -------------
 247
 248 WARNING: mod_perl 1.99_xx is not supported.
 249
 250 Add a few lines to your Apache 2.xx configuration file, so that
 251 it knows where to find RT:
 252
 253 <VirtualHost your.ip.address>
 254     ServerName your.rt.server.hostname
 255
 256     DocumentRoot /opt/rt3/share/html
 257     AddDefaultCharset UTF-8
 258
 259     # optional apache logs for RT
 260     # ErrorLog /opt/rt3/var/log/apache2.error
 261     # TransferLog /opt/rt3/var/log/apache2.access
 262
 263     PerlRequire "/opt/rt3/bin/webmux.pl"
 264
 265     <Location /NoAuth/images>
 266         SetHandler default
 267     </Location>
 268     <Location />
 269         SetHandler perl-script
 270         PerlResponseHandler RT::Mason
 271     </Location>
 272 </VirtualHost>
 273
 274 FastCGI
 275 -------
 276
 277 Installation with FastCGI is a little bit more complex and is documented
 278 in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration
 279
 280 In the most basic configuration, you can set up your webserver to run
 281 as a user who is a member of the "rt" unix group so that the FastCGI script
 282 can read RT's configuration file.  It's important to understand the security
 283 implications of this configuration, which are discussed in the document
 284 mentioned above.
 285
 286 To install RT with FastCGI, you'll need to add a few lines to your
 287 Apache configuration file telling it about RT:
 288
 289
 290 # Tell FastCGI to put its temporary files somewhere sane.
 291 FastCgiIpcDir /tmp
 292
 293 FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120
 294
 295 <VirtualHost rt.example.com>
 296    ServerName your.rt.server.hostname
 297
 298    # Pass through requests to display images
 299    Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
 300
 301    AddHandler fastcgi-script fcgi
 302    ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
 303 </VirtualHost>
 304
 305
 306
 307 SETTING UP THE MAIL GATEWAY
 308 ---------------------------
 309
 310 To let email flow to your RT server, you need to add a few lines of
 311 configuration to your mail server's "aliases" file. These lines "pipe"
 312 incoming email messages from your mail server to RT.
 313
 314 Add the following lines to /etc/aliases (or your local equivalent) on your mail server:
 315
 316 rt:         "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://rt.example.com/"
 317 rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/"
 318
 319 You'll need to add similar lines for each queue you want to be able
 320 to send email to. To find out more about how to configure RT's email
 321 gateway, type:
 322
 323        perldoc /opt/rt3/bin/rt-mailgate
 324
 325
 326
 327 GETTING HELP
 328 ------------
 329
 330 If RT is mission-critical for you or if you use it heavily, we recommend that
 331 you purchase a commercial support contract.  Details on support contracts
 332 are available at http://www.bestpractical.com or by writing to
 333 <sales@bestpractical.com>.
 334
 335 If you're interested in having RT extended or customized or would like more
 336 information about commercial support options, please send email to
 337 <sales@bestpractical.com> to discuss rates and availability.
 338
 339
 340
 341 RT WEBSITE
 342 ----------
 343
 344 For current information about RT, check out the RT website at
 345      http://www.bestpractical.com/
 346
 347 You'll find screenshots, a pointer to the current version of RT, contributed
 348 patches, and lots of other great stuff.
 349
 350
 351
 352 RT-USERS MAILING LIST
 353 ---------------------
 354
 355 To keep up to date on the latest RT tips, techniques and extensions,
 356 you probably want to join the rt-users mailing list.  Send a message to:
 357
 358       rt-users-request@lists.bestpractical.com
 359
 360 with the body of the message consisting of only the word:
 361
 362      subscribe
 363
 364 If you're interested in hacking on RT, you'll want to subscribe to
 365 <rt-devel@lists.bestpractical.com>.  Subscribe to it with instructions
 366 similar to those above.
 367
 368 Address questions about the stable release to the rt-users list, and
 369 questions about the development version to the rt-devel list.  If you feel
 370 your questions are best not asked publicly, send them personally to
 371 <jesse@bestpractical.com>.
 372
 373
 374
 375 BUGS
 376 ----
 377
 378 RT's a pretty complex application, and as you get up to speed, you might
 379 run into some trouble. Generally, it's best to ask about things you
 380 run into on the rt-users mailinglist (or pick up a commercial support
 381 contract from Best Practical). But, sometimes people do run into bugs. In
 382 the exceedingly unlikely event that you hit a bug in RT, please report
 383 it! We'd love to hear about problems you have with RT, so we can fix them.
 384 To report a bug, send email to rt-bugs@fsck.com.
 385
 386
 387 # BEGIN BPS TAGGED BLOCK {{{
 388 #
 389 # COPYRIGHT:
 390 #
 391 # This software is Copyright (c) 1996-2009 Best Practical Solutions, LLC
 392 #                                          <jesse@bestpractical.com>
 393 #
 394 # (Except where explicitly superseded by other copyright notices)
 395 #
 396 #
 397 # LICENSE:
 398 #
 399 # This work is made available to you under the terms of Version 2 of
 400 # the GNU General Public License. A copy of that license should have
 401 # been provided with this software, but in any event can be snarfed
 402 # from www.gnu.org.
 403 #
 404 # This work is distributed in the hope that it will be useful, but
 405 # WITHOUT ANY WARRANTY; without even the implied warranty of
 406 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 407 # General Public License for more details.
 408 #
 409 # You should have received a copy of the GNU General Public License
 410 # along with this program; if not, write to the Free Software
 411 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 412 # 02110-1301 or visit their web page on the internet at
 413 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
 414 #
 415 #
 416 # CONTRIBUTION SUBMISSION POLICY:
 417 #
 418 # (The following paragraph is not intended to limit the rights granted
 419 # to you to modify and distribute this software under the terms of
 420 # the GNU General Public License and is only of importance to you if
 421 # you choose to contribute your changes and enhancements to the
 422 # community by submitting them to Best Practical Solutions, LLC.)
 423 #
 424 # By intentionally submitting any modifications, corrections or
 425 # derivatives to this work, or any other work intended for use with
 426 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
 427 # you are the copyright holder for those contributions and you grant
 428 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
 429 # royalty-free, perpetual, license to use, copy, create derivative
 430 # works based on those contributions, and sublicense and distribute
 431 # those contributions and any derivatives thereof.
 432 #
 433 # END BPS TAGGED BLOCK }}}