README 13.2 KB
Newer Older
Jesse Vincent's avatar
Jesse Vincent committed
1
2
3
RT is an enterprise-grade issue tracking system. It allows organizations
to keep track of what needs to get done, who is working on which tasks,
what's already been done, and when tasks were (or weren't) completed.
Jesse Vincent's avatar
Jesse Vincent committed
4

Jesse Vincent's avatar
Jesse Vincent committed
5
6
7
RT doesn't cost anything to use, no matter how much you use it; it
is freely available under the terms of Version 2 of the GNU General
Public License.
8

9
10
RT is commercially-supported software. To purchase support, training,
custom development, or professional services, please get in touch with
Jesse Vincent's avatar
Jesse Vincent committed
11
us at sales@bestpractical.com.
Jesse Vincent's avatar
Jesse Vincent committed
12

Jesse Vincent's avatar
Jesse Vincent committed
13
14
15
     Jesse Vincent
     Best Practical Solutions, LLC
     March, 2005
16
17


18
19
20
REQUIRED PACKAGES:
------------------

21
o   Perl 5.8.3 or later (http://www.perl.com).
Jesse Vincent's avatar
Jesse Vincent committed
22

Jesse Vincent's avatar
Jesse Vincent committed
23
24
       Perl versions prior to 5.8.3 contain bugs that could result
       in data corruption. We recommend strongly that you use 5.8.3
25
       or newer.
Jesse Vincent's avatar
Jesse Vincent committed
26
27

o   A supported SQL database
28

Jesse Vincent's avatar
Jesse Vincent committed
29
        Currently supported:  Mysql 4.0.13 or later with InnoDB support.
30
                              Postgres 7.2 or later.
31
                              Oracle 9iR2 or later.
32
                              SQLite 3.0. (Not recommended for production)
33

34
o   Apache version 1.3.x or 2.x (http://httpd.apache.org) 
Jesse Vincent's avatar
Jesse Vincent committed
35
36
        with mod_perl -- (http://perl.apache.org ) 
        or a webserver with FastCGI support (www.fastcgi.com)
37

38
        Compiling mod_perl on Apache 1.3.x as a DSO has been known 
Jesse Vincent's avatar
Jesse Vincent committed
39
        to have massive stability problems and is not recommended.
40

41
        mod_perl 1.x must be built with EVERYTHING=1
42

43
        RT's FastCGI handler needs to access RT's configuration file.
44

45
o    Various and sundry perl modules
46
47
48
49
50
	A tool included with RT takes care of the installation of
	most of these automatically during the install process.

	The tool supplied with RT uses Perl's CPAN system
	(http://www.cpan.org) to install modules. Some operating
51
	systems package all or some of the modules required, and
52
	you may be better off installing the modules that way.
53
54
55
56
57


GENERAL INSTALLATION
--------------------

Jesse Vincent's avatar
Jesse Vincent committed
58
59
60
61
This is a rough guide to installing RT. For more detail, you'll
want to read a more comprehensive installation guide at:

    http://wiki.bestpractical.com/index.cgi?InstallationGuides
62

Jesse Vincent's avatar
Jesse Vincent committed
63
1   Unpack this distribution other than where you want to install RT
64

Jesse Vincent's avatar
Jesse Vincent committed
65
     To do this cleanly, run the following command:
66

Jesse Vincent's avatar
Jesse Vincent committed
67
       tar xzvf rt.tar.gz -C /tmp
68

Jesse Vincent's avatar
Jesse Vincent committed
69
2   Run the "configure" script. 
70

Jesse Vincent's avatar
Jesse Vincent committed
71
72
       ./configure --help to see the list of options
       ./configure (with the flags you want)
73

Jesse Vincent's avatar
Jesse Vincent committed
74
75
    RT defaults to installing in /opt/rt3 with MySQL as its database. It
    tries to guess which of www-data, www, apache or nobody your webserver
Alex Vandiver's avatar
Alex Vandiver committed
76
77
78
    will run as, but you can override that behavior.  Note that the
    default install directory in /opt/rt3 does not work under SELinux's
    default configuration.
79

Jesse Vincent's avatar
Jesse Vincent committed
80
3   Make sure that RT has everything it needs to run.
Jesse Vincent's avatar
Jesse Vincent committed
81

Jesse Vincent's avatar
Jesse Vincent committed
82
    Check for missing dependencies by running:
Jesse Vincent's avatar
Jesse Vincent committed
83

Jesse Vincent's avatar
Jesse Vincent committed
84
       make testdeps        
85

Jesse Vincent's avatar
Jesse Vincent committed
86
87
88
4   If the script reports any missing dependencies, install them by hand
    or run the following command as a user who has permission to install perl
    modules on your system:
89

Jesse Vincent's avatar
Jesse Vincent committed
90
     make fixdeps
Jesse Vincent's avatar
Jesse Vincent committed
91

92
93
    Some modules require user input or environment variables to install correctly,
    so it may be necessary to install them manually.
94

Jesse Vincent's avatar
Jesse Vincent committed
95
96
97
5   Check to make sure everything was installed properly.
     
       make testdeps
98

Jesse Vincent's avatar
Jesse Vincent committed
99
100
     It might sometimes be necessary to run "make fixdeps" several times
     to install all necessary perl modules.
101

Jesse Vincent's avatar
Jesse Vincent committed
102
103
104
6   If this is a new installation:
     
     As a user with permission to install RT in your chosen directory, type:
Jesse Vincent's avatar
Jesse Vincent committed
105

Jesse Vincent's avatar
Jesse Vincent committed
106
107
108
109
110
       make install   
                    
     Set up etc/RT_SiteConfig.pm in your RT installation directory.
     You'll need to add any values you need to change from the defaults 
     in etc/RT_Config.pm
111

Jesse Vincent's avatar
Jesse Vincent committed
112
113
114
     As a user with permission to read RT's configuration file, type:
     
       make initialize-database 
115

Jesse Vincent's avatar
Jesse Vincent committed
116
117
118
     If the make fails, type:
     
       make dropdb 
119

Jesse Vincent's avatar
Jesse Vincent committed
120
     and start over from step 6
121

Jesse Vincent's avatar
Jesse Vincent committed
122
7   If you're upgrading from RT 3.0 or newer:
123

Jesse Vincent's avatar
Jesse Vincent committed
124
125
126
127
     Read through the UPGRADING document included in this distribution.
     
     It includes special upgrade instructions that will help you get this
     new version of RT up and running smoothly.
128

Jesse Vincent's avatar
Jesse Vincent committed
129
130
     As a user with permission to install RT in your chosen installation
     directory, type: 
131

Jesse Vincent's avatar
Jesse Vincent committed
132
       make upgrade    
133

Jesse Vincent's avatar
Jesse Vincent committed
134
135
     This will install new binaries, config files and libraries without
     overwriting your RT database. 
Jesse Vincent's avatar
Jesse Vincent committed
136

Jesse Vincent's avatar
Jesse Vincent committed
137
138
139
     Update etc/RT_SiteConfig.pm in your RT installation directory.
     You'll need to add any new values you need to change from the defaults 
     in etc/RT_Config.pm
140

Jesse Vincent's avatar
Jesse Vincent committed
141
     You may also need to update RT's database.  To find out, type:
142

Jesse Vincent's avatar
Jesse Vincent committed
143
144
145
146
       ls etc/upgrade

     For each item in that directory whose name is greater than
     your previously installed RT version, run:
147

Jesse Vincent's avatar
Jesse Vincent committed
148
149
150
151
152
153
       /opt/rt3/sbin/rt-setup-database --action schema \
           --datadir etc/upgrade/<version>
       /opt/rt3/sbin/rt-setup-database --action acl \
           --datadir etc/upgrade/<version>
       /opt/rt3/sbin/rt-setup-database --action insert \
            --datadir etc/upgrade/<version>
154

Jesse Vincent's avatar
Jesse Vincent committed
155
156
157
158
159
160
161
     Clear mason cache dir:

       rm -fr /opt/rt3/var/mason_data/obj

     Stop and start web-server.


Jesse Vincent's avatar
Jesse Vincent committed
162
8  If you're upgrading from RT 2.0:
163

Jesse Vincent's avatar
Jesse Vincent committed
164
165
    Please upgrade from RT 2.0 to RT 3.2 and then follow the instructions
    for section 7.
166

Jesse Vincent's avatar
Jesse Vincent committed
167
9   Configure the email and web gateways, as described below. 
168
169

    NOTE: root's password for the web interface is "password" 
170
    (without the quotes).  Not changing this is a SECURITY risk!
171
    
Jesse Vincent's avatar
Jesse Vincent committed
172
10   Set up users, groups, queues, scrips and access control.
173

174
    Until you do this, RT will not be able to send or receive email,
175
176
177
178
    nor will it be more than marginally functional.  This is not an
    optional step.


179
180


Jesse Vincent's avatar
Jesse Vincent committed
181
182
SETTING UP THE WEB INTERFACE
----------------------------
183

184
RT's web interface is based around HTML::Mason, which works well with
185
186
187
188
189
190
191
the mod_perl perl interpreter within Apache httpd and FastCGI.

Once you've set up the web interface, consider setting up automatic 
logout for inactive sessions. For more information about how to do that,
run 
    perldoc /path/to/rt/sbin/rt-clean-sessions

192

193
194
mod_perl 1.xx
-------------
195

196
197
198
199
200
201
WARNING: mod_perl 1.99_xx is not supported.

See below configuration instructions for mod_perl 2.x

To install RT with mod_perl 1.x, you'll need to install the
apache database connection cache. To make sure it's installed, run
Jesse Vincent's avatar
Jesse Vincent committed
202
203
the following command:

204
    perl -MCPAN -e'install "Apache::DBI"'
Jesse Vincent's avatar
Jesse Vincent committed
205

206
Next, add a few lines to your Apache 1.3.xx configuration file, so that
Jesse Vincent's avatar
Jesse Vincent committed
207
it knows where to find RT:
208
209

<VirtualHost your.ip.address>
210
    ServerName your.rt.server.hostname
211

Jesse Vincent's avatar
Jesse Vincent committed
212
    DocumentRoot /opt/rt3/share/html
213
214
    AddDefaultCharset UTF-8

215
216
217
218
    # optional apache logs for RT
    # ErrorLog /opt/rt3/var/log/apache.error
    # TransferLog /opt/rt3/var/log/apache.access

219
    PerlModule Apache::DBI
Jesse Vincent's avatar
Jesse Vincent committed
220
    PerlRequire /opt/rt3/bin/webmux.pl
221

222
223
224
    <Location /NoAuth/images>
        SetHandler default
    </Location>
Jesse Vincent's avatar
Jesse Vincent committed
225
    <Location />
226
227
        SetHandler perl-script
        PerlHandler RT::Mason
Jesse Vincent's avatar
Jesse Vincent committed
228
    </Location>
229
230
</VirtualHost>

231
232
233
234
235
236
237
238
239
240
241
mod_perl 2.xx
-------------

WARNING: mod_perl 1.99_xx is not supported.

Add a few lines to your Apache 2.xx configuration file, so that
it knows where to find RT:

<VirtualHost your.ip.address>
    ServerName your.rt.server.hostname

242
243
244
    DocumentRoot /opt/rt3/share/html
    AddDefaultCharset UTF-8

245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
    # optional apache logs for RT
    # ErrorLog /opt/rt3/var/log/apache2.error
    # TransferLog /opt/rt3/var/log/apache2.access

    PerlRequire "/opt/rt3/bin/webmux.pl"

    <Location /NoAuth/images>
        SetHandler default
    </Location>
    <Location />
        SetHandler perl-script
        PerlResponseHandler RT::Mason
    </Location>
</VirtualHost>

260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
FastCGI
-------

Installation with FastCGI is a little bit more complex and is documented 
in detail at http://wiki.bestpractical.com/index.cgi?FastCGIConfiguration

In the most basic configuration, you can set up your webserver to run
as a user who is a member of the "rt" unix group so that the FastCGI script
can read RT's configuration file.  It's important to understand the security
implications of this configuration, which are discussed in the document
mentioned above.

To install RT with FastCGI, you'll need to add a few lines to your 
Apache configuration file telling it about RT:

275
276
<VirtualHost your.ip.address>
   ServerName your.rt.server.hostname
277
278
279

   # Pass through requests to display images
   Alias /NoAuth/images/ /opt/rt3/share/html/NoAuth/images/
280

281
282
283
284
285
286
287
288
289
   # Tell FastCGI to put its temporary files somewhere sane.
   FastCgiIpcDir /tmp

   FastCgiServer /opt/rt3/bin/mason_handler.fcgi -idle-timeout 120

   AddHandler fastcgi-script fcgi
   ScriptAlias / /opt/rt3/bin/mason_handler.fcgi/
</VirtualHost>

290
291


Jesse Vincent's avatar
Jesse Vincent committed
292
293
SETTING UP THE MAIL GATEWAY 
---------------------------
294

Jesse Vincent's avatar
Jesse Vincent committed
295
296
297
To let email flow to your RT server, you need to add a few lines of
configuration to your mail server's "aliases" file. These lines "pipe"
incoming email messages from your mail server to RT.
298

Jesse Vincent's avatar
Jesse Vincent committed
299
Add the following lines to /etc/aliases (or your local equivalent) on your mail server:
300

Jesse Vincent's avatar
Jesse Vincent committed
301
302
rt:         "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://rt.example.com/"
rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/"
303

Jesse Vincent's avatar
Jesse Vincent committed
304
305
306
307
308
You'll need to add similar lines for each queue you want to be able
to send email to. To find out more about how to configure RT's email
gateway, type:

       perldoc /opt/rt3/bin/rt-mailgate
309
310
311
312
313
314
315
316



GETTING HELP
------------

If RT is mission-critical for you or if you use it heavily, we recommend that
you purchase a commercial support contract.  Details on support contracts
Jesse Vincent's avatar
Jesse Vincent committed
317
are available at http://www.bestpractical.com or by writing to
Jesse Vincent's avatar
Jesse Vincent committed
318
<sales@bestpractical.com>.
319
320
321
322
323
324

If you're interested in having RT extended or customized or would like more
information about commercial support options, please send email to 
<sales@bestpractical.com> to discuss rates and availability.


Jesse Vincent's avatar
Jesse Vincent committed
325
326
327
328
329
330
331
332
333
334
335
336

RT WEBSITE
----------

For current information about RT, check out the RT website at 
     http://www.bestpractical.com/  

You'll find screenshots, a pointer to the current version of RT, contributed 
patches, and lots of other great stuff.



337
RT-USERS MAILING LIST
338
339
--------------------

340
341
To keep up to date on the latest RT tips, techniques and extensions,
you probably want to join the rt-users mailing list.  Send a message to:
342

Jesse Vincent's avatar
Jesse Vincent committed
343
      rt-users-request@lists.bestpractical.com 
344

345
with the body of the message consisting of only the word:
346

Jesse Vincent's avatar
Jesse Vincent committed
347
     subscribe
348

349
If you're interested in hacking on RT, you'll want to subscribe to
Jesse Vincent's avatar
Jesse Vincent committed
350
<rt-devel@lists.bestpractical.com>.  Subscribe to it with instructions
Jesse Vincent's avatar
Jesse Vincent committed
351
similar to those above.
352
353
354

Address questions about the stable release to the rt-users list, and
questions about the development version to the rt-devel list.  If you feel
355
your questions are best not asked publicly, send them personally to
356
357
358
<jesse@bestpractical.com>.


359

Jesse Vincent's avatar
Jesse Vincent committed
360
361
BUGS
----
Jesse Vincent's avatar
Jesse Vincent committed
362

363
RT's a pretty complex application, and as you get up to speed, you might
Jesse Vincent's avatar
Jesse Vincent committed
364
365
366
367
368
369
run into some trouble. Generally, it's best to ask about things you
run into on the rt-users mailinglist (or pick up a commercial support
contract from Best Practical). But, sometimes people do run into bugs. In
the exceedingly unlikely event that you hit a bug in RT, please report
it! We'd love to hear about problems you have with RT, so we can fix them.
To report a bug, send email to rt-bugs@fsck.com.
Jesse Vincent's avatar
Jesse Vincent committed
370
371
372
373
374
375


# BEGIN BPS TAGGED BLOCK {{{
# 
# COPYRIGHT:
#  
376
# This software is Copyright (c) 1996-2007 Best Practical Solutions, LLC 
Jesse Vincent's avatar
Jesse Vincent committed
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
#                                          <jesse@bestpractical.com>
# 
# (Except where explicitly superseded by other copyright notices)
# 
# 
# LICENSE:
# 
# This work is made available to you under the terms of Version 2 of
# the GNU General Public License. A copy of that license should have
# been provided with this software, but in any event can be snarfed
# from www.gnu.org.
# 
# This work is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
Ruslan Zakirov's avatar
Ruslan Zakirov committed
396
397
398
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301 or visit their web page on the internet at
# http://www.gnu.org/copyleft/gpl.html.
Jesse Vincent's avatar
Jesse Vincent committed
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
# 
# 
# CONTRIBUTION SUBMISSION POLICY:
# 
# (The following paragraph is not intended to limit the rights granted
# to you to modify and distribute this software under the terms of
# the GNU General Public License and is only of importance to you if
# you choose to contribute your changes and enhancements to the
# community by submitting them to Best Practical Solutions, LLC.)
# 
# By intentionally submitting any modifications, corrections or
# derivatives to this work, or any other work intended for use with
# Request Tracker, to Best Practical Solutions, LLC, you confirm that
# you are the copyright holder for those contributions and you grant
# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
414
# royalty-free, perpetual license to use, copy, create derivative
Jesse Vincent's avatar
Jesse Vincent committed
415
416
417
418
# works based on those contributions, and sublicense and distribute
# those contributions and any derivatives thereof.
# 
# END BPS TAGGED BLOCK }}}