-*- readme-debian -*-

Installation notes for the Debian package request-tracker5

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/rt5-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-tracker5/RT_SiteConfig.pm
file. The recommended way is to place configuration files with a .pm
extension into the directory /etc/request-tracker5/RT_SiteConfig.d. Since
RT 4.4, these files will be read at runtime, and the separate update
step is no longer needed.

Note that the default settings in
/usr/share/request-tracker5/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.

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-tracker5 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 rt5-db-mysql or rt5-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-5 --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-tracker5/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.

WEB SERVER INTEGRATION
----------------------

RT generally needs to be run with a frontend web server. Most commonly,
Apache is used with mod_fcgid, but integration with the non-free
mod_fastcgi, mod_perl and other web servers is also supported.

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

There are three config files supplied in /etc/request-tracker5/ for the
different modes of operation: mod_perl2, fastcgi and fcgid.  These files are
supplied by the rt5-apache2 package.  By default these will configure
Apache to serve your RT instance at /rt, once they are included in a
VirtualHost section. They may need further customisations for your 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 (normally defined in /etc/request-tracker5/apache2-*).

FastCGI
=======

Customise one of
/etc/request-tracker5/apache2-fcgid.conf (mod_fcgid) or
/etc/request-tracker5/apache2-fastcgi.conf (mod_fastcgi) and then
activate the configuration using the instructions at the top of the
relevant file.

mod_perl
========

Customise /etc/request-tracker5/apache2-modperl2.conf and then activate
the configuration using the instructions at the top of the file.


EXTERNAL FCGI DAEMON
--------------------

The rt5-fcgi package contains extra configuration for running RT as
an external process, suitable for other web servers (for example nginx)
with support for talking to FCGI processes via sockets. See
/usr/share/doc/rt5-fcgi/README.Debian for more information.

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 rt5-clients package, in README.Debian.


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

Note that we have added another configuration file called
/etc/request-tracker5/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-tracker5/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>, Fri, 01 Jan 2016 17:29:30 +0000