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
|