]>
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 | ||
af59614d | 17 | o Perl 5.10.1 or later (http://www.perl.org). |
84fb5b46 | 18 | |
af59614d | 19 | RT won't start on versions of Perl older than 5.10.1. |
84fb5b46 MKG |
20 | |
21 | o A supported SQL database | |
22 | ||
af59614d MKG |
23 | Currently supported: MySQL 5.1 or later with InnoDB support. |
24 | Postgres 8.4 or later; 9.0 or later suggested | |
84fb5b46 | 25 | Oracle 9iR2 or later. |
af59614d MKG |
26 | SQLite 3.0 or later; for testing only, no |
27 | upgrade path guaranteed | |
84fb5b46 MKG |
28 | |
29 | o Apache version 1.3.x or 2.x (http://httpd.apache.org) | |
30 | with mod_perl -- (http://perl.apache.org) | |
c33a4027 | 31 | or with FastCGI -- (http://www.fastcgi.com) |
84fb5b46 MKG |
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 | |
c33a4027 MKG |
69 | in docs/UPGRADING-* If you are coming from 4.0.x to 4.2.x you should |
70 | review both the UPGRADING-4.0 and UPGRADING-4.2 file. Similarly, if | |
71 | you were coming from 3.8.x, you would want to review UPGRADING-3.8, | |
72 | UPGRADING-4.0 and UPGRADING-4.2 | |
84fb5b46 MKG |
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 | ||
af59614d MKG |
95 | If you are having trouble installing GD, refer to "Installing GD libraries" |
96 | in docs/charts.pod. Ticket relationship graphing requires the graphviz | |
97 | library which you should install using your distribution's package manager. | |
84fb5b46 MKG |
98 | |
99 | 5) Check to make sure everything was installed properly. | |
100 | ||
101 | make testdeps | |
102 | ||
103 | It might sometimes be necessary to run "make fixdeps" several times | |
104 | to install all necessary perl modules. | |
105 | ||
106 | 6a) If this is a NEW installation (not an upgrade): | |
107 | ||
108 | As a user with permission to install RT in your chosen directory, | |
109 | type: | |
110 | ||
111 | make install | |
112 | ||
113 | To configure RT with the web installer, run: | |
114 | ||
115 | /opt/rt4/sbin/rt-server | |
116 | ||
117 | and follow the instructions. Once completed, you should now have a | |
118 | working RT instance running with the standalone rt-server. Press | |
119 | Ctrl-C to stop it, and proceed to Step 7 to configure a recommended | |
120 | deployment environment for production. | |
121 | ||
122 | To configure RT manually, you must setup etc/RT_SiteConfig.pm in | |
123 | your RT installation directory. You'll need to add any values you | |
124 | need to change from the defaults in etc/RT_Config.pm | |
125 | ||
126 | As a user with permission to read RT's configuration file, type: | |
127 | ||
128 | make initialize-database | |
129 | ||
130 | If the make fails, type: | |
131 | ||
132 | make dropdb | |
133 | ||
134 | and re-run 'make initialize-database'. | |
135 | ||
136 | 6b) If you are UPGRADING from a previous installation: | |
137 | ||
138 | Before upgrading, always ensure that you have a complete current | |
139 | backup. If you don't have a current backup, upgrading your database | |
140 | could accidentally damage it and lose data, or worse. | |
141 | ||
142 | If you are using MySQL, please read the instructions in | |
143 | docs/UPGRADING.mysql as well to ensure that you do not corrupt | |
144 | existing data. | |
145 | ||
146 | First, stop your webserver. You may also wish to put incoming email | |
147 | into a hold queue, to avoid temporary delivery failure messages if | |
148 | your upgrade is expected to take several hours. | |
149 | ||
150 | Next, install new binaries, config files and libraries by running: | |
151 | ||
152 | make upgrade | |
153 | ||
154 | This will also prompt you to upgrade your database by running: | |
155 | ||
156 | make upgrade-database | |
157 | ||
158 | You should back up your database before running this command. | |
159 | When you run it, you will be prompted for your previous version of | |
c33a4027 | 160 | RT (such as 3.8.1) so that the appropriate set of database |
84fb5b46 MKG |
161 | upgrades can be applied. |
162 | ||
c33a4027 MKG |
163 | If 'make upgrade-database' completes without error, your upgrade |
164 | has been successful and you may restart your webserver. | |
84fb5b46 MKG |
165 | |
166 | 7) Configure the web server, as described in docs/web_deployment.pod, | |
167 | and the email gateway, as described below. | |
168 | ||
169 | NOTE: The default credentials for RT are: | |
170 | User: root | |
171 | Pass: password | |
172 | Not changing the root password from the default is a SECURITY risk! | |
173 | ||
174 | Once you've set up the web interface, consider setting up automatic | |
175 | logout for inactive sessions. For more information about how to do | |
176 | that, run: | |
177 | ||
178 | perldoc /path/to/rt/sbin/rt-clean-sessions | |
179 | ||
180 | 8) 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, nor | |
183 | will it be more than marginally functional. This is not an optional | |
184 | step. | |
185 | ||
186 | 9) Set up automated recurring tasks (cronjobs): | |
187 | ||
188 | To generate email digest messages, you must arrange for the provided | |
189 | utility to be run once daily, and once weekly. You may also want to | |
190 | arrange for the rt-email-dashboards utility to be run hourly. For | |
c33a4027 MKG |
191 | example, if your task scheduler is cron, you can configure it by |
192 | adding the following lines as /etc/cron.d/rt: | |
193 | ||
194 | 0 0 * * * root /opt/rt4/sbin/rt-email-digest -m daily | |
195 | 0 0 * * 0 root /opt/rt4/sbin/rt-email-digest -m weekly | |
196 | 0 * * * * root /opt/rt4/sbin/rt-email-dashboards | |
84fb5b46 MKG |
197 | |
198 | 10) Configure the RT email gateway. To let email flow to your RT | |
199 | server, you need to add a few lines of configuration to your mail | |
200 | server's "aliases" file. These lines "pipe" incoming email messages | |
201 | from your mail server to RT. | |
202 | ||
203 | Add the following lines to /etc/aliases (or your local equivalent) | |
204 | on your mail server: | |
205 | ||
206 | rt: "|/opt/rt4/bin/rt-mailgate --queue general --action correspond --url http://rt.example.com/" | |
207 | rt-comment: "|/opt/rt4/bin/rt-mailgate --queue general --action comment --url http://rt.example.com/" | |
208 | ||
209 | You'll need to add similar lines for each queue you want to be able to | |
210 | send email to. To find out more about how to configure RT's email | |
211 | gateway, type: | |
212 | ||
213 | perldoc /opt/rt4/bin/rt-mailgate | |
214 | ||
84fb5b46 MKG |
215 | |
216 | GETTING HELP | |
217 | ------------ | |
218 | ||
219 | If RT is mission-critical for you or if you use it heavily, we recommend | |
220 | that you purchase a commercial support contract. Details on support | |
221 | contracts are available at http://www.bestpractical.com or by writing to | |
222 | <sales@bestpractical.com>. | |
223 | ||
224 | If you're interested in having RT extended or customized or would like | |
225 | more information about commercial support options, please send email to | |
226 | <sales@bestpractical.com> to discuss rates and availability. | |
227 | ||
228 | ||
229 | MAILING LISTS AND WIKI | |
230 | ---------------------- | |
231 | ||
232 | To keep up to date on the latest RT tips, techniques and extensions, you | |
233 | may wish to join the rt-users mailing list. Send a message to: | |
234 | ||
235 | rt-users-request@lists.bestpractical.com | |
236 | ||
237 | with the body of the message consisting of only the word: | |
238 | ||
239 | subscribe | |
240 | ||
241 | If you're interested in hacking on RT, you'll want to subscribe to | |
242 | <rt-devel@lists.bestpractical.com>. Subscribe to it with instructions | |
243 | similar to those above. Address questions about the stable release to | |
244 | the rt-users list, and questions about the development version to the | |
245 | rt-devel list. | |
246 | ||
247 | The RT wiki, at http://requesttracker.wikia.com/ , is also a potential | |
248 | resource. | |
249 | ||
250 | ||
251 | SECURITY | |
252 | -------- | |
253 | ||
254 | If you believe you've discovered a security issue in RT, please send an | |
255 | email to <security@bestpractical.com> with a detailed description of the | |
256 | issue, and a secure means to respond to you (such as your PGP public | |
257 | key). You can find our PGP key and fingerprint at | |
258 | http://bestpractical.com/security/ | |
259 | ||
260 | ||
261 | BUGS | |
262 | ---- | |
263 | ||
264 | RT's a pretty complex application, and as you get up to speed, you might | |
265 | run into some trouble. Generally, it's best to ask about things you run | |
266 | into on the rt-users mailinglist (or pick up a commercial support | |
267 | contract from Best Practical). But, sometimes people do run into | |
268 | bugs. In the exceedingly unlikely event that you hit a bug in RT, please | |
269 | report it! We'd love to hear about problems you have with RT, so we can | |
270 | fix them. To report a bug, send email to <rt-bugs@bestpractical.com>. | |
271 | ||
272 | ||
273 | # BEGIN BPS TAGGED BLOCK {{{ | |
274 | # | |
275 | # COPYRIGHT: | |
276 | # | |
320f0092 | 277 | # This software is Copyright (c) 1996-2014 Best Practical Solutions, LLC |
84fb5b46 MKG |
278 | # <sales@bestpractical.com> |
279 | # | |
280 | # (Except where explicitly superseded by other copyright notices) | |
281 | # | |
282 | # | |
283 | # LICENSE: | |
284 | # | |
285 | # This work is made available to you under the terms of Version 2 of | |
286 | # the GNU General Public License. A copy of that license should have | |
287 | # been provided with this software, but in any event can be snarfed | |
288 | # from www.gnu.org. | |
289 | # | |
290 | # This work is distributed in the hope that it will be useful, but | |
291 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
292 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
293 | # General Public License for more details. | |
294 | # | |
295 | # You should have received a copy of the GNU General Public License | |
296 | # along with this program; if not, write to the Free Software | |
297 | # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA | |
298 | # 02110-1301 or visit their web page on the internet at | |
299 | # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html. | |
300 | # | |
301 | # | |
302 | # CONTRIBUTION SUBMISSION POLICY: | |
303 | # | |
304 | # (The following paragraph is not intended to limit the rights granted | |
305 | # to you to modify and distribute this software under the terms of | |
306 | # the GNU General Public License and is only of importance to you if | |
307 | # you choose to contribute your changes and enhancements to the | |
308 | # community by submitting them to Best Practical Solutions, LLC.) | |
309 | # | |
310 | # By intentionally submitting any modifications, corrections or | |
311 | # derivatives to this work, or any other work intended for use with | |
312 | # Request Tracker, to Best Practical Solutions, LLC, you confirm that | |
313 | # you are the copyright holder for those contributions and you grant | |
314 | # Best Practical Solutions, LLC a nonexclusive, worldwide, irrevocable, | |
315 | # royalty-free, perpetual, license to use, copy, create derivative | |
316 | # works based on those contributions, and sublicense and distribute | |
317 | # those contributions and any derivatives thereof. | |
318 | # | |
319 | # END BPS TAGGED BLOCK }}} |