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