]>
Commit | Line | Data |
---|---|---|
84fb5b46 MKG |
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 is | |
6 | freely available under the terms of Version 2 of the GNU General Public | |
7 | 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 | ||
84fb5b46 MKG |
13 | |
14 | REQUIRED PACKAGES | |
15 | ----------------- | |
16 | ||
17 | o Perl 5.8.3 or later (http://www.perl.org). | |
18 | ||
19 | Perl versions prior to 5.8.3 contain bugs that could result in | |
20 | data corruption. RT won't start on older versions. | |
21 | ||
22 | o A supported SQL database | |
23 | ||
24 | Currently supported: Mysql 4.1 or later with InnoDB support. | |
25 | Postgres 8.1 or later. | |
26 | Oracle 9iR2 or later. | |
27 | SQLite 3.0. (Not recommended for production) | |
28 | ||
29 | o Apache version 1.3.x or 2.x (http://httpd.apache.org) | |
30 | with mod_perl -- (http://perl.apache.org) | |
31 | or with FastCGI -- (www.fastcgi.com) | |
32 | or other webserver with FastCGI support | |
33 | ||
34 | RT's FastCGI handler needs to access RT's configuration file. | |
35 | ||
36 | o Various and sundry perl modules | |
37 | ||
38 | A tool included with RT takes care of the installation of most | |
39 | of these automatically during the install process. | |
40 | ||
41 | The tool supplied with RT uses Perl's CPAN (http://www.cpan.org) | |
42 | to install modules. Some operating systems package all or some | |
43 | of the modules required, and you may be better off installing | |
44 | the modules that way. | |
45 | ||
46 | ||
47 | GENERAL INSTALLATION | |
48 | -------------------- | |
49 | ||
50 | 1) Unpack this distribution other than where you want to install RT. | |
51 | To do this cleanly, run the following command: | |
52 | ||
53 | tar xzvf rt.tar.gz -C /tmp | |
54 | ||
55 | 2) Run the "configure" script. To see the list of options, run: | |
56 | ||
57 | ./configure --help | |
58 | ||
59 | Peruse the options, then rerun ./configure with the flags you want. | |
60 | ||
61 | RT defaults to installing in /opt/rt4 with MySQL as its database. It | |
62 | tries to guess which of www-data, www, apache or nobody your | |
63 | webserver will run as, but you can override that behavior. Note | |
64 | that the default install directory in /opt/rt4 does not work under | |
65 | SELinux's default configuration. | |
66 | ||
67 | If you are upgrading from a previous version of RT, please review | |
68 | the upgrade notes for the appropriate versions, which can be found | |
69 | in docs/UPGRADING-* If you are coming from 3.8.6 to 4.0.x you should | |
70 | review both the UPGRADING-3.8 and UPGRADING-4.0 file. Similarly, if | |
71 | you were coming from 3.6.7, you would want to review UPGRADING-3.6, | |
72 | UPGRADING-3.8 and UPGRADING-4.0 | |
73 | ||
74 | It is particularly important that you read the warnings at the top of | |
75 | UPGRADING-4.0 for some common issues. | |
76 | ||
77 | RT stores the arguments given to ./configure at the top of the | |
78 | etc/RT_Config.pm file in case you need to recreate your previous use | |
79 | of ./configure. | |
80 | ||
81 | 3) Make sure that RT has the Perl and system libraries it needs to run. | |
82 | Check for missing dependencies by running: | |
83 | ||
84 | make testdeps | |
85 | ||
86 | 4) If the script reports any missing dependencies, install them by | |
87 | hand, or run the following command as a user who has permission to | |
88 | install perl modules on your system: | |
89 | ||
90 | make fixdeps | |
91 | ||
92 | Some modules require user input or environment variables to install | |
93 | correctly, so it may be necessary to install them manually. | |
94 | ||
95 | If you are installing with CPAN module older than 1.84, you will | |
96 | need to start CPAN (by running perl -MCPAN -e shell) and upgrade the | |
97 | CPAN shell with: | |
98 | ||
99 | install CPAN | |
100 | ||
101 | If you are unsure of your CPAN version, it will be printed when you | |
102 | run the shell. | |
103 | ||
104 | If you are having trouble installing GD or Graphviz, you should | |
105 | install gd-devel and the graphviz libraries using your | |
106 | distribution's package manager. | |
107 | ||
108 | 5) Check to make sure everything was installed properly. | |
109 | ||
110 | make testdeps | |
111 | ||
112 | It might sometimes be necessary to run "make fixdeps" several times | |
113 | to install all necessary perl modules. | |
114 | ||
115 | 6a) If this is a NEW installation (not an upgrade): | |
116 | ||
117 | As a user with permission to install RT in your chosen directory, | |
118 | type: | |
119 | ||
120 | make install | |
121 | ||
122 | To configure RT with the web installer, run: | |
123 | ||
124 | /opt/rt4/sbin/rt-server | |
125 | ||
126 | and follow the instructions. Once completed, you should now have a | |
127 | working RT instance running with the standalone rt-server. Press | |
128 | Ctrl-C to stop it, and proceed to Step 7 to configure a recommended | |
129 | deployment environment for production. | |
130 | ||
131 | To configure RT manually, you must setup etc/RT_SiteConfig.pm in | |
132 | your RT installation directory. You'll need to add any values you | |
133 | need to change from the defaults in etc/RT_Config.pm | |
134 | ||
135 | As a user with permission to read RT's configuration file, type: | |
136 | ||
137 | make initialize-database | |
138 | ||
139 | If the make fails, type: | |
140 | ||
141 | make dropdb | |
142 | ||
143 | and re-run 'make initialize-database'. | |
144 | ||
145 | 6b) If you are UPGRADING from a previous installation: | |
146 | ||
147 | Before upgrading, always ensure that you have a complete current | |
148 | backup. If you don't have a current backup, upgrading your database | |
149 | could accidentally damage it and lose data, or worse. | |
150 | ||
151 | If you are using MySQL, please read the instructions in | |
152 | docs/UPGRADING.mysql as well to ensure that you do not corrupt | |
153 | existing data. | |
154 | ||
155 | First, stop your webserver. You may also wish to put incoming email | |
156 | into a hold queue, to avoid temporary delivery failure messages if | |
157 | your upgrade is expected to take several hours. | |
158 | ||
159 | Next, install new binaries, config files and libraries by running: | |
160 | ||
161 | make upgrade | |
162 | ||
163 | This will also prompt you to upgrade your database by running: | |
164 | ||
165 | make upgrade-database | |
166 | ||
167 | You should back up your database before running this command. | |
168 | When you run it, you will be prompted for your previous version of | |
169 | RT (such as 3.6.4) so that the appropriate set of database | |
170 | upgrades can be applied. | |
171 | ||
172 | Finally, clear the Mason cache dir: | |
173 | ||
174 | rm -fr /opt/rt4/var/mason_data/obj | |
175 | ||
176 | You may then start your web server again. | |
177 | ||
178 | 7) Configure the web server, as described in docs/web_deployment.pod, | |
179 | and the email gateway, as described below. | |
180 | ||
181 | NOTE: The default credentials for RT are: | |
182 | User: root | |
183 | Pass: password | |
184 | Not changing the root password from the default is a SECURITY risk! | |
185 | ||
186 | Once you've set up the web interface, consider setting up automatic | |
187 | logout for inactive sessions. For more information about how to do | |
188 | that, run: | |
189 | ||
190 | perldoc /path/to/rt/sbin/rt-clean-sessions | |
191 | ||
192 | 8) Set up users, groups, queues, scrips and access control. | |
193 | ||
194 | Until you do this, RT will not be able to send or receive email, nor | |
195 | will it be more than marginally functional. This is not an optional | |
196 | step. | |
197 | ||
198 | 9) Set up automated recurring tasks (cronjobs): | |
199 | ||
200 | To generate email digest messages, you must arrange for the provided | |
201 | utility to be run once daily, and once weekly. You may also want to | |
202 | arrange for the rt-email-dashboards utility to be run hourly. For | |
203 | example, if your task scheduler is cron, you can configure it as | |
204 | follows: | |
205 | ||
206 | crontab -e # as the RT administrator (probably root) | |
207 | # insert the following lines: | |
208 | 0 0 * * * /opt/rt4/sbin/rt-email-digest -m daily | |
209 | 0 0 * * 0 /opt/rt4/sbin/rt-email-digest -m weekly | |
210 | 0 * * * * /opt/rt4/sbin/rt-email-dashboards | |
211 | ||
212 | 10) Configure the RT email gateway. To let email flow to your RT | |
213 | server, you need to add a few lines of configuration to your mail | |
214 | server's "aliases" file. These lines "pipe" incoming email messages | |
215 | from your mail server to RT. | |
216 | ||
217 | Add the following lines to /etc/aliases (or your local equivalent) | |
218 | on your mail server: | |
219 | ||
220 | rt: "|/opt/rt4/bin/rt-mailgate --queue general --action correspond --url http://rt.example.com/" | |
221 | rt-comment: "|/opt/rt4/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/" | |
222 | ||
223 | You'll need to add similar lines for each queue you want to be able to | |
224 | send email to. To find out more about how to configure RT's email | |
225 | gateway, type: | |
226 | ||
227 | perldoc /opt/rt4/bin/rt-mailgate | |
228 | ||
229 | If your webserver uses SSL, rt-mailgate will require several new | |
230 | Perl libraries. RT can detect and install these for you automatically | |
231 | if you include --enable-ssl-mailgate when running configure and then | |
232 | run make fixdeps as described in step 4. It is safe to rerun configure | |
233 | and make fixdeps after you have installed RT, you should be sure to include | |
234 | all the arguments you used in step 2 plus --enable-ssl-mailgate. | |
235 | ||
236 | ||
237 | GETTING HELP | |
238 | ------------ | |
239 | ||
240 | If RT is mission-critical for you or if you use it heavily, we recommend | |
241 | that you purchase a commercial support contract. Details on support | |
242 | contracts are available at http://www.bestpractical.com or by writing to | |
243 | <sales@bestpractical.com>. | |
244 | ||
245 | If you're interested in having RT extended or customized or would like | |
246 | more information about commercial support options, please send email to | |
247 | <sales@bestpractical.com> to discuss rates and availability. | |
248 | ||
249 | ||
250 | MAILING LISTS AND WIKI | |
251 | ---------------------- | |
252 | ||
253 | To keep up to date on the latest RT tips, techniques and extensions, you | |
254 | may wish to join the rt-users mailing list. Send a message to: | |
255 | ||
256 | rt-users-request@lists.bestpractical.com | |
257 | ||
258 | with the body of the message consisting of only the word: | |
259 | ||
260 | subscribe | |
261 | ||
262 | If you're interested in hacking on RT, you'll want to subscribe to | |
263 | <rt-devel@lists.bestpractical.com>. Subscribe to it with instructions | |
264 | similar to those above. Address questions about the stable release to | |
265 | the rt-users list, and questions about the development version to the | |
266 | rt-devel list. | |
267 | ||
268 | The RT wiki, at http://requesttracker.wikia.com/ , is also a potential | |
269 | resource. | |
270 | ||
271 | ||
272 | SECURITY | |
273 | -------- | |
274 | ||
275 | If you believe you've discovered a security issue in RT, please send an | |
276 | email to <security@bestpractical.com> with a detailed description of the | |
277 | issue, and a secure means to respond to you (such as your PGP public | |
278 | key). You can find our PGP key and fingerprint at | |
279 | http://bestpractical.com/security/ | |
280 | ||
281 | ||
282 | BUGS | |
283 | ---- | |
284 | ||
285 | RT's a pretty complex application, and as you get up to speed, you might | |
286 | run into some trouble. Generally, it's best to ask about things you run | |
287 | into on the rt-users mailinglist (or pick up a commercial support | |
288 | contract from Best Practical). But, sometimes people do run into | |
289 | bugs. In the exceedingly unlikely event that you hit a bug in RT, please | |
290 | report it! We'd love to hear about problems you have with RT, so we can | |
291 | fix them. To report a bug, send email to <rt-bugs@bestpractical.com>. | |
292 | ||
293 | ||
294 | # BEGIN BPS TAGGED BLOCK {{{ | |
295 | # | |
296 | # COPYRIGHT: | |
297 | # | |
403d7b0b | 298 | # This software is Copyright (c) 1996-2013 Best Practical Solutions, LLC |
84fb5b46 MKG |
299 | # <sales@bestpractical.com> |
300 | # | |
301 | # (Except where explicitly superseded by other copyright notices) | |
302 | # | |
303 | # | |
304 | # LICENSE: | |
305 | # | |
306 | # This work is made available to you under the terms of Version 2 of | |
307 | # the GNU General Public License. A copy of that license should have | |
308 | # been provided with this software, but in any event can be snarfed | |
309 | # from www.gnu.org. | |
310 | # | |
311 | # This work is distributed in the hope that it will be useful, but | |
312 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
313 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
314 | # General Public License for more details. | |
315 | # | |
316 | # You should have received a copy of the GNU General Public License | |
317 | # along with this program; if not, write to the Free Software | |
318 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA | |
319 | # 02110-1301 or visit their web page on the internet at | |
320 | # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html. | |
321 | # | |
322 | # | |
323 | # CONTRIBUTION SUBMISSION POLICY: | |
324 | # | |
325 | # (The following paragraph is not intended to limit the rights granted | |
326 | # to you to modify and distribute this software under the terms of | |
327 | # the GNU General Public License and is only of importance to you if | |
328 | # you choose to contribute your changes and enhancements to the | |
329 | # community by submitting them to Best Practical Solutions, LLC.) | |
330 | # | |
331 | # By intentionally submitting any modifications, corrections or | |
332 | # derivatives to this work, or any other work intended for use with | |
333 | # Request Tracker, to Best Practical Solutions, LLC, you confirm that | |
334 | # you are the copyright holder for those contributions and you grant | |
335 | # Best Practical Solutions, LLC a nonexclusive, worldwide, irrevocable, | |
336 | # royalty-free, perpetual, license to use, copy, create derivative | |
337 | # works based on those contributions, and sublicense and distribute | |
338 | # those contributions and any derivatives thereof. | |
339 | # | |
340 | # END BPS TAGGED BLOCK }}} |