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.
25 RT is an enterprise-grade issue tracking system. It allows
26 organizations to keep track of their to-do lists, who is working
27 on which tasks, what's already been done, and when tasks were
28 completed. It is available under the terms of version 2 of the GNU
29 General Public License (GPL), so it doesn't cost anything to set
34 Best Practical Solutions, LLC
40 o Perl 5.8.3 or later (http://www.perl.com).
42 (If you intend to use the FastCGI or SpeedyCGI support, you
43 need to make sure that perl has been built with support for
44 setgid perl scripts.)`
46 Perl versions prior to 5.8.3 contain bugs that could result in data
47 corruption. We recommend strongly that you use 5.8.3 or newer.
49 Perl 5.6.1 is currently deprecated and will be officially desupported
52 o A DB backend; MySQL is recommended ( http://www.mysql.com )
53 Currently supported: Mysql 4.0.13 or later.
54 Postgres 7.2 or later.
57 o Apache version 1.3.x or 2.x (http://httpd.apache.org)
58 with mod_perl -- (http://perl.apache.org )
59 or a webserver with FastCGI support (www.fastcgi.com)
61 mod_perl 2.0 isn't quite ready for prime_time just yet;
62 Best Practical Solutions strongly recommends that sites use
63 Apache 1.3 or FastCGI.
65 Compiling mod_perl on Apache 1.3.x as a DSO has been known
66 to have massive stability problems and is not recommended.
68 mod_perl 1.x must be build with EVERYTHING=1
70 RT's FastCGI handler runs setgid to the 'rt' group to
71 protect RT's database password. You may need to install
72 a special "suidperl" package or reconfigure your perl
73 setup to support "setuid scripts" if you intend to use RT
76 Debian GNU/* 3.0+: the package which installs suidperl is
77 called perl-suid, and should work without any tweaking.
79 FreeBSD 4.2+: the package is called sperl, and should
80 install a suidperl that just works
82 Conectiva Linux 6.0+: suidperl is installed by default when
83 perl is installed, but the program /bin/suidperl is not setuid.
84 You must use chmod to make it setuid.
88 o Various and sundry perl modules
89 A tool included with RT takes care of the installation of
90 most of these automatically during the install process.
92 The tool supplied with RT uses Perl's CPAN system
93 (http://www.cpan.org) to install modules. Some operating
94 systems package all or some of the modules required and
95 you may be better off installing the modules that way.
101 This is a rough guide to installing RT. For more detail, you'll want
102 to read 'Chapter 2: Installing' in RT's manual, available at
103 http://www.bestpractical.com/rt
105 1 Unpack this distribution SOMWHERE OTHER THAN where you want to install RT
107 Granted, you've already got it open. To do this cleanly:
109 tar xzvf rt.tar.gz -C /tmp
111 2 Run the "configure" script.
113 ./configure --help to see the list of options
114 ./configure (with the flags you want)
116 3 Satisfy RT's myriad dependencies.
118 3.1 Check for compliance:
120 perl sbin/rt-test-dependencies \
121 --with-<databasename> --with-<web-environment>
123 databasename is one of: mysql, postgres, oracle
124 web-environment is one of: fastcgi, modperl1, modperl2
126 3.2 If there are unsatisfied dependencies, install them by hand or run:
128 perl sbin/rt-test-dependencies \
129 --with-<databasename> --with-<web-environment> --install
132 3.3 Check to make sure everything was installed properly:
134 perl sbin/rt-test-dependencies \
135 --with-<databasename> --with-<web-environment>
137 4 Create a group called 'rt'
139 5a FOR A NEW INSTALLATION:
142 make install (replace "make" with the local name for
143 Make, if you need to)
146 make initialize-database
149 If the make fails, type:
151 and start over from step 5a
153 5b FOR UPGRADING: (Within the RT 3.0.x series)
156 Read through the UPGRADING document included in this distribution.
157 It may contain important instructions for updating your database
160 make upgrade (replace "make" with the local name for
161 Make, if you need to)
163 This will build new binaries, config files and libraries without
164 overwriting your RT database.
166 It may then instruct you to update your RT system database objects
168 5c FOR UPGRADING: (From RT 2.0.x)
170 Download the RT2 to RT3 migration tools from:
172 http://bestpractical.com/pub/rt/devel/rt2-to-rt3.tar.gz
174 Follow the included instructions.
176 6 Edit etc/RT_SiteConfig.pm in your RT installation directory, by specifying
177 any values you need to change from the defaults in etc/RT_Config.pm
179 7 Configure the email and web gateways, as described below.
181 8 Stop and start your webserver, so it picks up your configuration changes.
183 NOTE: root's password for the web interface is "password"
184 (without the quotes.) Not changing this is a SECURITY risk
186 9 Configure RT per the instructions in RT's manual.
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
196 RT's web interface is based around HTML::Mason, which works best with the mod_perl
197 perl interpreter within Apache httpd. Alternatively, support for the FastCGI
198 (and plain CGI) interface is also provided as 'bin/mason_handler.fcgi'.
201 You'll need to add a few lines to your httpd.conf telling it about RT:
203 <VirtualHost your.ip.address>
204 ServerName your.rt.server.hostname
205 DocumentRoot /opt/rt3/share/html
206 AddDefaultCharset UTF-8
208 # these four lines apply to Apache2+mod_perl2 only: {{{
209 PerlSetVar MasonArgsMethod CGI
210 PerlModule Apache2 Apache::compat
212 RewriteRule ^(.*)/$ $1/index.html
215 PerlModule Apache::DBI
216 PerlRequire /opt/rt3/bin/webmux.pl
219 SetHandler perl-script
220 PerlHandler RT::Mason
226 SETTING UP THE MAIL GATEWAY
227 ---------------------------
229 An alias for the initial queue will need to be made in either your
230 global mail aliases file (if you are using NIS) or locally on your
233 Add the following lines to /etc/aliases (or your local equivalent) :
235 rt: "|/opt/rt3/bin/rt-mailgate --queue general --action correspond --url http://localhost/"
236 rt-comment: "|/opt/rt3/bin/rt-mailgate --queue general --action comment --url http://localhost/"
238 <queue-name>----/ | |
240 <correspond or comment depending on whether | |
241 the mail should be resent to the requestor>---/ |
243 <URL for RT's web interface>---/
249 To report a bug, send email to rt-3.0-bugs@fsck.com.
254 If RT is mission-critical for you or if you use it heavily, we recommend that
255 you purchase a commercial support contract. Details on support contracts
256 are available at http://www.bestpractical.com.
258 If you're interested in having RT extended or customized or would like more
259 information about commercial support options, please send email to
260 <sales@bestpractical.com> to discuss rates and availability.
266 To keep up to date on the latest RT tips, techniques and extensions,
267 you probably want to join the rt-users mailing list. Send a message to:
269 rt-users-request@lists.fsck.com
271 With the body of the message consisting of only the word:
275 If you're interested in hacking on RT, you'll want to subscribe to
276 rt-devel@lists.fsck.com. Subscribe to it with instructions similar to
279 Address questions about the stable release to the rt-users list, and
280 questions about the development version to the rt-devel list. If you feel
281 your questions are best not asked publicly, send them personally to
282 <jesse@bestpractical.com>.
288 For current information about RT, check out the RT website at
289 http://www.bestpractical.com/
291 You'll find screenshots, a pointer to the current version of RT, contributed
292 patches, and lots of other great stuff.
298 If the solution to the problem you're running into isn't obvious and you've
299 checked the FAQ, feel free to send mail to rt-users@fsck.com (for released
300 versions of RT) or rt-devel@fsck.com (for development versions).