						-*- readme-debian -*-

Installation notes for the Debian package request-tracker4

Although the installation procedure should get the RT configuration into
a runnable state, manual configuration is currently still required for
integration with the web server (see the Apache section below) and the
mail transport system (see /usr/share/doc/rt4-clients/README.Debian).
There are also quite a lot of things left to tune in the RT configuration
itself; let's start with this.

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

The configuration is done via the /etc/request-tracker4/RT_SiteConfig.pm
file. The recommended way is to place configuration snippets into
the directory /etc/request-tracker4/RT_SiteConfig.d and run
update-rt-siteconfig afterwards to regenerate RT_SiteConfig.pm.

Note that the default settings in 
/usr/share/request-tracker4/etc/RT_Config.pm
are used for any options you do not put into RT_SiteConfig.pm.

We recommend that you read RT_Config.pm thoroughly and copy/edit the
extra bits you think you need into files in the RT_SiteConfig.d directory.

Note that the RT_SiteConfig.pm file 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. If you only update the file via update-rt-siteconfig, this is
of course taken care of automatically.

As the configuration file is a Perl module you can of course use any
Perl you like to handle the setting of the configuration options.

DATABASE CHOICE
---------------

If you installed request-tracker4 on its own, the database support
pulled in was SQLite; however, this isn't recommended by upstream for
production use.

We strongly recommend that you use MySQL or PostgreSQL for production
use, by installing rt4-db-mysql or rt4-db-postgresql.

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

There are two ways to go about setting up the database: dbconfig-common
and manual setup. The installation procedure should ask you if you want 
to use dbconfig-common; in this case everything should happen automatically
provided that the database server can be accessed with the database
administrator password you enter.

However, if it doesn't work for you or you prefer manual configuration
for some reason, there's still the "old" way:

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, first choose a password
for the 'root' user of the RT system (this is not the same as your
system root password, or the database password):

# touch /root/rt-pass
# chmod 700 /root/rt-pass
<edit /root/rt-pass to add your password on its own>

Then do:
# /usr/sbin/rt-setup-database-4 --action init --dba rtuser \
    --prompt-for-dba-password --root-password-file /root/mypass

<give the database password for the rtuser SQL account when prompted>

This needs access to /etc/request-tracker4/RT_SiteConfig.pm, so the
command usually has to be run as root.

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


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

There are three config files supplied in /etc/request-tracker4/ for the
different modes of operation: mod_perl2, fastcgi and fcgid.
These might work straight away; you really should read them before
beginning to use RT4. The expectation is that you will need to edit
the applicable file for your RT4 site.

In particular, if you are running RT within a Virtualhost (and therefore
cannot address it at http://localhost), you *will* need to adjust the ACL
for /rt/REST/1.0/NoAuth to add the IP address or name of the VirtualHost
(assuming that you are running the mail gateway on the same system).

Whichever of the three configuration files you decide to use you will
need to ensure you have the correct apache2 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-tracker4/html

2)

<Location /rt/>
</Location>

3)

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

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

   RewriteEngine off

from the relevant VirtualHost section in your config.

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-tracker4/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

or "a2enmod perl".

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

FastCGI
=======

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

/etc/request-tracker4/apache2-fastcgi.conf
/etc/request-tracker4/apache2-fcgid.conf

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

Include "/etc/request-tracker4/apache2-fastcgi.conf"

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


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

If you used a dbconfig-based install or followed the instructions above,
this section isn't relevant. Otherwise, if you ran rt-setup-database without
the --root-password-file option, then once the RT web interface is up
and running you should login as root IMMEDIATELY and change the default
password. The initial root password is 'password' (without the quotes, of
course). Go to 'Preferences' then 'About me'. You can then change the
password (and other pertinent information).

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

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


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

Note that we have added another configuration file called
/etc/request-tracker4/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-tracker4/html/ tree to avoid losing your
precious changes on upgrade of the Debian package.

Authors
-------

Stephen Quinney <sjq@debian.org>, Thu Sep 15 14:53:16 2005
Dominic Hargreaves <dom@earth.li>, Sun Jan 30 13:17:49 UTC 2011
