File: NOTES.Debian

package info (click to toggle)
request-tracker3.6 3.6.1-4%2Betch1
  • links: PTS
  • area: main
  • in suites: etch
  • size: 9,028 kB
  • ctags: 1,371
  • sloc: perl: 27,270; sh: 671; makefile: 327
file content (290 lines) | stat: -rw-r--r-- 9,802 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
						-*- readme-debian -*-

Installation notes for the Debian package request-tracker3.6

BASIC RT CONFIGURATION
----------------------

The first step is to configure RT, this is done via the
/etc/request-tracker3.6/RT_SiteConfig.pm file. Start by editing the file
as installed. Note that the default settings in RT_Config.pm are used
for any options you do put into RT_SiteConfig.pm. You should *NEVER*
edit the RT_Config.pm file directly; always use RT_SiteConfig.pm.

Changing the variables in the distributed RT_SiteConfig.pm should be
enough to get RT3 up and running but will probably not solve all your
problems. We recommend that you read /etc/request-tracker3.6/RT_Config.pm
thoroughly and copy/edit the extra bits you think you need into the
RT_SiteConfig.pm file.

The RT_SiteConfig.pm is a real Perl module and as such really does
need that last line which looks like:

1;

without it things will not work properly so please do not delete
it. As it is a Perl module you can of course use any Perl you like to
handle the setting of the configuration options.


DATABASE CREATION AND SCHEMA INSTALLATION
-----------------------------------------

1. Create the database user

As the database administrator (e.g. the postgres or mysql user), or
user with rights to create new users and databases, manually create
the RT user with SQL like:

(Postgres)
  CREATE USER rtuser WITH PASSWORD 'wibble' CREATEDB NOCREATEUSER;

(MySQL)
  GRANT ALL PRIVILEGES ON rtdb.* TO rtuser@localhost IDENTIFIED BY 'wibble';

Of course, rtuser and 'wibble' should be replaced with whatever you
have configured the $DatabaseUser and $DatabasePassword variables to
be in the RT_SiteConfig.pm. The database name is also defined there,
by the variable $DatabaseName -- in this file, we use 'rtdb'.

2. Configure the database access permissions

Ensure that you can access the database server as the rtuser SQL user.

For MySQL, you have probably already done this in stage 1.

You could do this for PostgreSQL with psql:

psql -d template1 -U rtuser -W

enter the password at the prompt.

If this fails (it probably will with the default Debian PostgreSQL
installation) then you probably need to change the access permissions
that you have set for your database server.

For PostgreSQL, this can be solved by editing the file
/etc/postgresql/pg_hba.conf and adding lines like these:

host    template1   rtuser    127.0.0.1    255.255.255.255   password
local   template1   rtuser                                   password
host    rtdb        rtuser    127.0.0.1    255.255.255.255   password
local   rtdb        rtuser                                   password

at the bottom of the file along with the other similar lines - but
above existing entries.

(rtdb is whatever you have configured the $DatabaseName variable to be
in the RT_SiteConfig.pm.)

Note that the order of entries in the pg_hba.conf _DOES MATTER_. The
first matching entry will be used and there is no fall through
mechanism if the first one fails. (See section 6.1 of the PostgreSQL
Administrator's manual for full details). The local entries above must
be put above the default local all/all if you want to able to access
the rtdb database as the rtuser from the command line using psql.

Restart the PostgreSQL server and try again with psql. If the database
server is on a different machine from that of the RT instance you will
need to configure these lines yourself.

Note that for PostgreSQL the rt-setup-database script needs permission
to connect to the template1 database as well as the RT
database. Giving permission to connect like this does not give out
actual read/write permission so doing this for the rt user can
generally be considered safe on the local system. Once you have
created and initialised your RT database you should remove the
template1 lines as they will not be needed for any other purpose.

Note: If you have problems with MySQL or know how to solve similar
issues for that server we would love to hear from you so we can extend
this help file.

3. Create and initialise the database

Now to populate the database with the schema, do:
# /usr/sbin/rt-setup-database-3.6 --action init --dba rtuser \
    --prompt-for-dba-password

<give the database password for the rtuser SQL account>


Note: if anything does go wrong in this procedure, you will probably
need to drop the database 'rtdb' manually.


APACHE CONFIGURATION
--------------------

There are four config files supplied in /etc/request-tracker3.6/ for the
different modes of operation: mod_perl1, mod_perl2, speedycgi,
fastcgi. These might work straight away; you really should read it
before beginning to use RT3.6. The expectation is that you will need to
edit the applicable file for your RT3.6 site.

Whichever of the four configuration files you decide to use you will
need to ensure you have the correct apache (1 or 2) modules
installed. You will also need to edit the RT_SiteConfig.pm to match up
these settings:

Set($WebPath , "/rt");
Set($WebBaseURL , "http://my.domain.com");

with any Apache virtual hosts, locations, aliases or rewrites in the
Include files, such as:

1)

Alias /rt /usr/share/request-tracker3.6/html

2)

ScriptAlias /rt /usr/share/request-tracker3.6/libexec/mason_handler.scgi

3)

<Location /rt/>
</Location>

4)

RewriteRule ^/rt$ /rt/
RewriteRule ^/rt/(.*)$ /usr/share/request-tracker3.6/html/$1

You should ensure that you remove any existing lines such as:

   RewriteEngine off

from the relevant VirtualHost section in your config.

For Apache1/modperl1 you probably want to edit the file
/etc/apache/httpd.conf.

You will almost certainly need to do some editing of this Include file.

mod_perl 1
=========

Add the following line to the VirtualHost section of Apache from which
you wish to serve RT.

Include "/etc/request-tracker3.6/apache-modperl.conf"

You will probably need to edit this Include file.

If you're using apache-perl you can skip the rest of this section.

You should check that the relevant lines for mod_perl in the Apache
httpd.config and make sure they are not commented out with a
preceeding '#'.

For Apache1.3 you will want to look for something like:

LoadModule perl_module        /usr/lib/apache/1.3/mod_perl.so

If you have the Debian apache-perl package then mod_perl is already
compiled in and you do not need to worry about this.

You may also need to, similarly, enable mod_rewrite, mod_actions (and
mod_ssl if you intend to use SSL)

mod_perl 2
=========

Add the following line to the VirtualHost section of Apache from which
you wish to serve RT, (possibly in the file
/etc/apache2/sites-enabled/default). When editing files in the apache2
sites-enabled and mods-enabled directories you should be very careful
not to leave behind editor backup files (such as *~ for emacs). These
will also be read when the server is restarted and cause general
confusion.

Include "/etc/request-tracker3.6/apache2-modperl2.conf"

You will probably need to edit this Include file.

For Apache2 you will want to look for something like:

LoadModule perl_module /usr/lib/apache2/modules/mod_perl.so

If you are using the standard Debian package it is just a case of doing:

ln -s /etc/apache2/mods-available/perl.load /etc/apache2/mods-enabled/perl.load

You may also need to, similarly, enable mod_rewrite, mod_actions (and
mod_ssl if you intend to use SSL)

fast/speedy cgi
===============

If you want to use something other than mod_perl, there are Mason
handler scripts in /etc/request-tracker3.6/. These are:

/etc/request-tracker3.6/apache-speedycgi.conf
/etc/request-tracker3.6/apache-fastcgi.conf

Again you will probably need to include these into the relevant
section of your Apache config with something like:

Include "/etc/request-tracker3.6/apache-fastcgi.conf"

Most likely they will require some editing before they do exactly what
you want.


RT ROOT PASSWORD
----------------

Once the web interface is running you need to login as root
IMMEDIATELY and change the default password and general
configuration. The initial root password is 'password' (without the
quotes, of course). Go to 'Configuration' then 'Users', follow the
'root' link. You can then alter the password and other pertinent
information.

REPEATED LOGIN REQUESTS
-----------------------

If the web interface repeatedly redirects you to the login prompt even
though you are already logged in, you may have misconfigured settings
in your MySQL database. A workaround is reported to be

 ALTER TABLE sessions CHANGE a_session a_session LONGBLOB;
 DELETE FROM sessions;

and an Apache restart. The right solution is to fix the database
configuration so that UTF8 strings don't get double encoded. See bug
#408405.

MAIL CONFIGURATION
------------------

Instructions on mail configuration can be found inside
the rt3.6-clients package, in README.Debian.


LOCAL MODIFICATIONS
-------------------

Note that we have added another configuration file called
/etc/request-tracker3.6/RT_SiteModules.pm. If you make any local
modifications to the HTML::Mason files you can have any necessary
extra Perl modules loaded at start time by putting the 'use'
statements in this file, e.g.:

use Net::LDAP;
1;

This means you do not need to edit webmux.pl which is the normal RT
way to do it. Any changes made to webmux.pl would not be preserved on
upgrading of the Debian package as it is not a Debian conffile.

If you do intend to change the look and feel of the site by editing
the HTML::Mason files you should, of course, do this in the
/usr/local/share/request-tracker3.6/html/ tree to avoid losing your
precious changes on upgrade of the Debian package.

This text was originally written by
Stephen Quinney <sjq@debian.org>, Thu Sep 15 14:53:16 2005

 -- Niko Tyni <ntyni@iki.fi> Mon, 21 Aug 2006 00:08:42 +0300