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