3 # Copyright (c) 1996-2003 Jesse Vincent <jesse@bestpractical.com>
5 # (Except where explictly superceded by other copyright notices)
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
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.
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.
24 RT is an enterprise-grade issue tracking system. It allows
25 organizations to keep track of their to-do lists, who is working
26 on which tasks, what's already been done, and when tasks were
27 completed. It is available under the terms of version 2 of the GNU
28 General Public License (GPL), so it doesn't cost anything to set
33 Best Practical Solutions, LLC
39 o Perl 5.8.0 or later (http://www.perl.com).
41 (If you intend to use the FastCGI or SpeedyCGI support, you
42 need to make sure that perl has been built with support for
43 setgid perl scripts.)`
45 Perl 5.6.1 is currently deprecated and will be officially desupported
48 o A DB backend; MySQL is recommended ( http://www.mysql.com )
49 Currently supported: Mysql 4.0.13 or later.
50 Postgres 7.2 or later.
52 Mysql 3.23.46 or newer with support for InnoDB
53 is currently deprecated and will be officially
54 desupported in a future release.
56 o Apache version 1.3.x or 2.x (http://httpd.apache.org)
57 with mod_perl -- (http://perl.apache.org )
58 or a webserver with FastCGI support (www.fastcgi.com)
60 mod_perl 2.0 isn't quite ready for prime_time just yet;
61 Best Practical Solutions strongly recommends that sites use
62 Apache 1.3 or FastCGI.
64 Compiling mod_perl on Apache 1.3.x as a DSO has been known
65 to have massive stability problems and is not recommended.
67 mod_perl 1.x must be build with EVERYTHING=1
69 RT's FastCGI handler runs setgid to the 'rt' group to
70 protect RT's database password. You may need to install
71 a special "suidperl" package or reconfigure your perl
72 setup to support "setuid scripts" if you intend to use RT
75 Debian GNU/* 3.0+: the package which installs suidperl is
76 called perl-suid, and should work without any tweaking.
78 FreeBSD 4.2+: the package is called sperl, and should
79 install a suidperl that just works
81 Conectiva Linux 6.0+: suidperl is installed by default when
82 perl is installed, but the program /bin/suidperl is not setuid.
83 You must use chmod to make it setuid.
87 o Various and sundry perl modules
88 A tool included with RT takes care of the installation of
89 most of these automatically during the install process.
91 The tool supplied with RT uses Perl's CPAN system
92 (http://www.cpan.org) to install modules. Some operating
93 systems package all or some of the modules required and
94 you may be better off installing the modules that way.
100 This is a rough guide to installing RT. For more detail, you'll want
101 to read 'Chapter 2: Installing' in RT's manual, available at
102 http://www.bestpractical.com/rt
104 1 Unpack this distribution SOMWHERE OTHER THAN where you want to install RT
106 Granted, you've already got it open. To do this cleanly:
108 tar xzvf rt.tar.gz -C /tmp
110 2 Run the "configure" script.
112 ./configure --help to see the list of options
113 ./configure (with the flags you want)
115 3 Satisfy RT's myriad dependencies.
117 3.1 Check for compliance:
119 perl sbin/rt-test-dependencies \
120 --with-<databasename> --with-<web-environment>
122 databasename is one of: mysql, postgres
123 web-environment is one of: fastcgi, modperl1, modperl2
125 3.2 If there are unsatisfied dependencies, install them by hand or run:
127 perl sbin/rt-test-dependencies \
128 --with-<databasename> --with-<web-environment> --install
131 3.3 Check to make sure everything was installed properly:
133 perl sbin/rt-test-dependencies \
134 --with-<databasename> --with-<web-environment>
136 4 Create a group called 'rt'
138 5a FOR A NEW INSTALLATION:
141 make install (replace "make" with the local name for
142 Make, if you need to)
145 make initialize-database
148 If the make fails, type:
150 and start over from step 5a
152 5b FOR UPGRADING: (Within the RT 3.0.x series)
155 make upgrade (replace "make" with the local name for
156 Make, if you need to)
158 This will build new binaries, config files and libraries without
159 overwriting your RT database.
161 It may then instruct you to update your RT system database objects
163 6 Edit etc/RT_SiteConfig.pm in your RT installation directory, by specifying
164 any values you need to change from the defaults in etc/RT_Config.pm
166 7 Configure the email and web gateways, as described below.
168 8 Stop and start your webserver, so it picks up your configuration changes.
170 NOTE: root's password for the web interface is "password"
171 (without the quotes.) Not changing this is a SECURITY risk
173 9 Configure RT per the instructions in RT's manual.
175 Until you do this, RT will not be able to send or receive email,
176 nor will it be more than marginally functional. This is not an
183 RT's web interface is based around HTML::Mason, which works best with the mod_perl
184 perl interpreter within Apache httpd. Alternatively, support for the FastCGI
185 (and plain CGI) interface is also provided as 'bin/mason_handler.fcgi'.
188 You'll need to add a few lines to your httpd.conf telling it about RT:
190 <VirtualHost your.ip.address>
191 ServerName your.rt.server.hostname
192 DocumentRoot /opt/rt3/share/html
193 AddDefaultCharset UTF-8
195 # this line applies to Apache2+mod_perl2 only
196 PerlModule Apache2 Apache::compat
198 PerlModule Apache::DBI
199 PerlRequire /opt/rt3/bin/webmux.pl
201 # this section applies to Apache 1 only
203 SetHandler perl-script
204 PerlHandler RT::Mason
207 # this section applies to Apache2+mod_perl2 only
208 <FilesMatch "\.html$">
209 SetHandler perl-script
210 PerlHandler RT::Mason
212 <LocationMatch "/Attachment/">
213 SetHandler perl-script
214 PerlHandler RT::Mason
216 <LocationMatch "/REST/">
217 SetHandler perl-script
218 PerlHandler RT::Mason
224 SETTING UP THE MAIL GATEWAY
225 ---------------------------
227 An alias for the initial queue will need to be made in either your
228 global mail aliases file (if you are using NIS) or locally on your
231 Add the following lines to /etc/aliases (or your local equivalent) :
233 rt: "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://localhost/"
234 rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://localhost/"
236 <queue-name>----/ | |
238 <correspond or comment depending on whether | |
239 the mail should be resent to the requestor>---/ |
241 <URL for RT's web interface>---/
247 To report a bug, send email to rt-3.0-bugs@fsck.com.
252 If RT is mission-critical for you or if you use it heavily, we recommend that
253 you purchase a commercial support contract. Details on support contracts
254 are available at http://www.bestpractical.com.
256 If you're interested in having RT extended or customized or would like more
257 information about commercial support options, please send email to
258 <sales@bestpractical.com> to discuss rates and availability.
264 To keep up to date on the latest RT tips, techniques and extensions,
265 you probably want to join the rt-users mailing list. Send a message to:
267 rt-users-request@lists.fsck.com
269 With the body of the message consisting of only the word:
273 If you're interested in hacking on RT, you'll want to subscribe to
274 rt-devel@lists.fsck.com. Subscribe to it with instructions similar to
277 Address questions about the stable release to the rt-users list, and
278 questions about the development version to the rt-devel list. If you feel
279 your questions are best not asked publicly, send them personally to
280 <jesse@bestpractical.com>.
286 For current information about RT, check out the RT website at
287 http://www.bestpractical.com/
289 You'll find screenshots, a pointer to the current version of RT, contributed
290 patches, and lots of other great stuff.
296 If the solution to the problem you're running into isn't obvious and you've
297 checked the FAQ, feel free to send mail to rt-users@fsck.com (for released
298 versions of RT) or rt-devel@fsck.com (for development versions).