2.2. Starting the Installation

< Day Day Up >

Get yourself a comfortable chair, a nice drink, some free hard disk space, and sit down for an hour or so of module building and configuration to install RT.

2.2.1. Step 1: Choose a Machine and Location

Like most database driven applications, RT is relatively resource intensive, especially on RAM. The more memory you can afford to dedicate to RT and its database server, the snappier it will feel and the happier your users will be. Fast CPUs and disks will help as well.

Also in this step, you should install the appropriate webserver and database, if those aren't installed yet.

There are good O'Reilly books on each of the supported databases, including Managing and Using MySQL, Practical PostgreSQL, and Oracle Essentials. Many of these books are also available on Safari, O'Reilly's online library, which makes searching convenient. You can access Safari by going to http://safari.oreilly.com.

2.2.2. Step 2: Download the RT Source Tarball

You can find information about the latest RT releases from the official RT download page at http://www.bestpractical.com/rt/download.html. In addition to the locations for packaged releases, this page also contains instructions on how to download the latest development copy of RT.

The latest stable release of RT is always available as http://download.bestpractical.com/pub/rt/release/rt.tar.gz, so you can grab that now, and place it in /tmp.

2.2.3. Step 3: Expand the tarball

With the tarball now in /tmp, unpack it with gunzip or an equivalent utility on your system:

     # gunzip -c rt.tar.gz | tar xvf -

This creates a directory named rt-3.x.x, where 3.x.x is the version of RT you downloaded. Make that directory your current working directory:

     # cd rt-3.x.x

Take a moment to read through the README file in your new RT directory. This file covers the basics of the installation, with brief instructions on how to do the install. More importantly, this file is the canonical location for updates to the installation procedure. If you are using Oracle, you'll also want to read the Oracle-specific instructions in the file README.Oracle. Finally, any special notes about upgrading an RT installation are in the file UPGRADING.

2.2.4. Step 4: Prepare to Configure

At this point, you'll need to know certain information in order to continue: The server architecture (mod_perl 1.x, mod_perl 2.x, FastCGI); database type (MySQL, PostgreSQL, or Oracle); where the database lives and the usernames and passwords to access it; and which Perl you want to use. If you don't have that information yet, pause and collect it now.

2.2.5. Step 5: Configure the RT Installation Process

Now you need to tell RT how to install itself by running the configure program. It takes a number of different options. We'll explain most of them here and in the following sections, but you can get a complete and current list with the help option:

     # ./configure --help

2.2.5.1. General configuration

You can install RT in any directory by using the prefix option, and it will put all of its files under that location. The default is /opt/rt3. Some users prefer to specify /usr/local/rt3. You can also put a private install in a location such as /home/you/projects/rt.

     --prefix=PREFIX         where to install RT's files to

Unless you change the configuration, RT will write any logs, session files, and HTML::Mason object cache files under the location you select, so you will want to choose a partition with a few hundred megabytes of free space.

Select alternate file layouts with enable-layout=inplace, enable-layout=FHS, and enable-layout=FreeBSD. See config.layout in the source directory for more information on each.

2.2.5.2. File ownership configuration

These settings (see Table 2-1) control the file ownership that will be used on all of the installed files. You must make sure that all the users and groups exist before you try and configure RT. They are optional unless you wish to change the detected defaults.

Table 2-1. File ownership
Option	Meaning
`with-rt-group=GROUP`	The group that owns all files (default: rt, rt3)
`with-bin-owner=OWNER`	The user that owns the RT binaries (default: root)
`with-libs-owner=OWNER`	The user that owns the RT libraries (default: root)
`with-libs-group=GROUP`	The group that owns the RT libraries (default: bin)
`with-web-user=USER`	The user the web server runs as (defaults: www, www-data, apache, httpd, nobody)
`with-web-group=GROUP`	The group the web server runs as (defaults: www, www-data, apache, httpd, nogroup, nobody)
`with-my-user-group`	Set all users and groups mentioned above to the current user and group (i.e. "you")

By default, RT assumes the existence of several users and groups on your system and will autodetect the defaults mentioned in this table. The standard configuration is to have all RT files owned by a 'rt' group. The installation process will chown or chgrp any files and directories that need to be accessible by the webserver.

These defaults are probably fine for most people installing into a system-wide directory like /opt/rt3 or /usr/local/rt3. The reason for this complex set of permissions is because only certain users/groups should be able to write to (and read) certain files for security purposes.

On some systems, the web-user and web-group should be set to "nobody", "apache" or "httpd." Look at the User and Group lines in your httpd.conf for details.

If you are performing a non-root install, (i.e., into your home directory or entirely as a special rt user) then you can use with-my-user-group to use only your current user and group. This will use the current value of the $USER or $LOGUSER environment variables and the first entry in the output of "groups".

2.2.5.3. Database configuration

RT needs to be able to talk to the database you've specified and also needs to create users and tables. To do this, it needs to know where you want your RT database to be. It also needs to know the username of an account that has permission to create and modify databases. For MySQL this is usually root but is configurable (see Table2-2). RT will prompt you for the administrator's password, so it can create the appropriate tables.

Table 2-2. Database options
Option	Meaning
`with-db-type=TYPE`	The type of database RT will use: `mysql`, `Pg`, `Oracle`, `SQLite` or `Informix` (default: mysql)
`with-db-host=HOSTNAME`	The fully qualified domain name of the database server (default: localhost)
`with-db-port=PORT`	The port on which the database listens
`with-db-rt-host=HOSTNAME`	The fully qualified domain name of RT server that talks to the database server (default: localhost)
`with-db-dba=DBA`	The name of the database administrator (default: root)
`with-db-database=DBNAME`	The name of the database to use (default: rt3)
`with-db-rt-user=DBUSER`	The name of the database user (default: rt_user)
`with-db-rt-pass=PASSWORD`	The password for the database user (default: rt_pass)

You will want to change the default password for the user RT will create. It's insecure to leave the default password of "rt_pass."

2.2.5.4. Perl configuration

Some systems have multiple instances or versions of Perl installed, and you don't always want to use the default one for RT. (This is especially true because RT requires a recent version of Perl to function properly.) Use the PERL environment variable to specify the location of the Perl binary you want RT to use. For example:

     $ env PERL=/usr/local/bin/perl ./configure     checking for a BSD-compatible install... /usr/bin/install -c     checking for perl... /usr/local/bin/perl     checking for chosen layout... RT3     checking if user www exists... not found     checking if user www-data exists... not found     checking if user apache exists... found     checking if group www exists... not found     checking if group www-data exists... not found     checking if group apache exists... found     checking if group rt3 exists... not found     checking if group rt exists... found     checking if group apache exists... found     which: no apachectl in (/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin)     configure: creating ./config.status     config.status: creating sbin/rt-dump-database     config.status: creating sbin/rt-setup-database     config.status: creating sbin/rt-test-dependencies     config.status: creating bin/mason_handler.fcgi     config.status: creating bin/mason_handler.scgi     config.status: creating bin/standalone_httpd     config.status: creating bin/rt-crontool     config.status: creating bin/rt-mailgate     config.status: creating bin/rt     config.status: creating Makefile     config.status: creating etc/RT_Config.pm     config.status: creating lib/RT.pm     config.status: creating bin/mason_handler.svc     config.status: creating bin/webmux.pl

This shows a default configuration of RT, using the Perl binary located at /usr/local/bin/perl and installing into the default location (/opt/rt3). Web scripts will be owned by the Apache user and in the Apache group. All other files will be in the rt group.

2.2.6. Step 6: Check for RT's Perl Dependencies

RT comes with a handy script called rt-test-dependencies that automatically queries your chosen version of Perl for all the modules that RT requires, and generates a report of what it finds. You can have RT run this script with the right options by issuing the following command:

     # make testdeps

The script will output a report similar to the following:

     /usr/local/bin/perl ./sbin/rt-test-dependencies --verbose --with-mysql     perl:             5.8.3...found     users:             rt group (apache)...found             bin owner (root)...found             libs owner (root)...found             libs group (bin)...found             web owner (apache)...found             web group (apache)...found     MASON dependencies:             Params::Validate 0.02...found             Cache::Cache ...found             Exception::Class 1.14...found             HTML::Mason 1.23...found             MLDBM ...found             Errno ...found             FreezeThaw ...found             Digest::MD5 2.27...found             CGI::Cookie 1.20...found             Storable 2.08...found             Apache::Session 1.53...found             XML::RSS ...found             HTTP::Server::Simple 0.07...MISSING                     HTTP::Server::Simple version 0.07 required this is only version 0.04     at (eval 41) line 2, <DATA> line 11.             HTTP::Server::Simple::Mason 0.03...found     MAILGATE dependencies:             HTML::TreeBuilder ...found             HTML::FormatText ...found             Getopt::Long ...found             LWP::UserAgent ...found     CLI dependencies:             Getopt::Long 2.24...found     CORE dependencies:             Digest::base ...found             Digest::MD5 2.27...found             DBI 1.37...found             Test::Inline ...found             Class::ReturnValue 0.40...found             DBIx::SearchBuilder 1.21...found             Text::Template ...found             File::Spec 0.8...found             HTML::Entities ...found             HTML::Scrubber 0.08...found             Net::Domain ...found             Log::Dispatch 2.0...found             Locale::Maketext 1.06...found             Locale::Maketext::Lexicon 0.32...found             Locale::Maketext::Fuzzy ...found             MIME::Entity 5.108...found             Mail::Mailer 1.57...found             Net::SMTP ...found             Text::Wrapper ...found             Time::ParseDate ...found             Time::HiRes ...found             File::Temp ...found             Term::ReadKey ...found             Text::Autoformat ...found             Text::Quoted 1.3...found             Tree::Simple 1.04...found             Scalar::Util ...found             Module::Versions::Report ...found             Cache::Simple::TimedExpiry ...found             XML::Simple ...found     DEV dependencies:             Regexp::Common ...found             Test::Inline ...found             Apache::Test ...found             HTML::Form ...found             HTML::TokeParser ...found             WWW::Mechanize ...found             Test::WWW::Mechanize ...found             Module::Refresh 0.03...found     MYSQL dependencies:             DBD::mysql 2.1018...found

If anything is missing, RT can use the CPAN.pm module to install it. If you haven't previously configured CPAN.pm, you need to do that before running this script. Run perl -MCPAN -eshell and follow the instructions. Then, RT can attempt to automatically install the necessary modules; run make fixdeps:

     # make fixdeps

This step requires either a network connection to contact a CPAN mirror or a local CPAN mirror, so that the installer can download any missing modules.

Earlier, you had the chance to specify three potentially different users and three groups: the user and group to own the scripts that RT installs, the user and group to own the libraries that RT installs, and the user and group that will run the web server process. At this point, you should make sure that these users and groups exist, because if they don't, the installation process will fail. How to do this depends on your system, but many systems provide the useradd and groupadd tools to automate the process. However you do it, create the users and groups now, if necessary.

2.2.7. Step 7: Install

RT will copy all the files to the appropriate location under PREFIX. If you are not doing a with-my-user-group install, you will need to run this as root, since the process changes the ownership and permission of many of the files.

     # make install

2.2.8. Step 8: Initialize the Database

RT will create the appropriate database, users, and initialize some tables when you run make initialize-database. (Do not run this more than once, unless you want to lose your data.)

     # make initialize-database     Creating mysql database rt.     Now populating database schema.     Creating database schema.     schema sucessfully inserted     Now inserting database ACLs     Now inserting RT core system objects     Checking for existing system user...not found.  This appears to be a new installation.     Creating system user...done.     Now inserting RT data     Creating Superuser  ACL...Creating groups...3.4.5.6.7.8.9.done.     Creating users...10.12.done.     Creating queues...1.2.done.     Creating ACL...2.3.done.     Creating ScripActions...1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.done.     Creating ScripConditions...1.2.3.4.5.6.7.8.9.done.     Creating templates...1.2.3.4.5.6.7.8.9.10.11.12.done.     Creating scrips...1.2.3.4.5.6.7.8.9.10.11.12.13.done.

At this point, RT is installed. The next step is to configure it and then configure your web servers and mail servers to talk to it properly. If you already have a webserver with mod_perl or FastCGI set up, the hard work is over.

Upgrading RT

The process for applying minor version upgrades to RT is very similar to installing RT. You perform all the steps before make install as if you were performing a new installation, but you run make upgrade instead. Be sure to run a dependency check (step #6 earlier), as new versions of RT may require new versions of modules.

make upgrade will re-install RT files over your old files, but won't overwrite your local customizations or data as long as you have followed the customization procedures in Chapter 8. Any other actions will be described in the UPGRADING file in the RT distribution.

Some upgrades require database changes. Usually these are just additions of new indexes or data. If you're performing such an upgrade, make upgrade will tell you how to run the appropriate files from etc/upgrade/.

If you're performing a major upgrade of RT that requires data conversion, such as from RT 2.x to 3.x, you'll need to follow the specific instructions documented in the README file.