ManualInstallation

This page 'ManualInstallation' is tagged as OUTDATED

This page contains out of date and possibly misleading information or instructions such as installation methods or configuration examples that no longer apply. Please consider this warning when reading the page below.

If you have checked or updated this page and found the content to be suitable, please remove this notice by editing the page and remove the Outdated template tag.

Prev: ManualRequirements --- Up: UserManual --- Next: ManualApacheConfig

---

GENERAL INSTALLATION

2. Run the configure script

From within the temporary directory you just created, run the "configure" script. You'll want to read this entire section, and decide on the option switches which you will want to specify to configure, before you actually run it. Having multiple console windows available during (this or any other) install is exceptionally helpful.

To see a list of configuration options, use the "help" flag, which will show you a list of options:

./configure --help

We've also listed the options here. Defaults are specified in brackets.

Configuration:
 -h, --help              display this help and exit
 --help=short        display options specific to this package
 --help=recursive    display the short help of all the included packages
 -V, --version           display version information and exit
 -q, --quiet, --silent   do not print `checking...' messages
 --cache-file=FILE   cache test results in FILE [disabled]
 -C, --config-cache      alias for `--cache-file=config.cache'
 -n, --no-create         do not create output files
 --srcdir=DIR        find the sources in DIR [configure dir or `..']

Installation directory

By default, `make install' will install all the files in `/opt/rt3/bin', `/opt/rt3/lib' etc. You can specify an installation prefix other than `/opt/rt3' using `--prefix', for instance `--prefix=$HOME'.

--prefix=PREFIX         install architecture-independent files in PREFIX
                         [/opt/rt3]
--exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                         [PREFIX]

Installation directory fine-tuning

Here are some more configure switches you can use to fine tune exactly where the install process should put its files. If you don't know why or to where you might change these, just accept the default.

--bindir=DIR           user executables [EPREFIX/bin]
--sbindir=DIR          system admin executables [EPREFIX/sbin]
--libexecdir=DIR       program executables [EPREFIX/libexec]
--datadir=DIR          read-only architecture-independent data [PREFIX/share]
--sysconfdir=DIR       read-only single-machine data [PREFIX/etc]
--sharedstatedir=DIR   modifiable architecture-independent data [PREFIX/com]
--localstatedir=DIR    modifiable single-machine data [PREFIX/var]
--libdir=DIR           object code libraries [EPREFIX/lib]
--includedir=DIR       C header files [PREFIX/include]
--oldincludedir=DIR    C header files for non-gcc [/usr/include]
--infodir=DIR          info documentation [PREFIX/info]
--mandir=DIR           man documentation [PREFIX/man]

Optional Features:

--disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
--enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
--enable-layout=LAYOUT  Use a specific directory layout (Default: RT3) Optional Packages:
--with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
--without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
--with-rt-group=GROUP   group to own all files (default: rt)
--with-bin-owner=OWNER  user that will own rt executable files (default root)
--with-libs-owner=OWNER user that will own RT libraries (default root)
--with-libs-group=GROUP group that will own rt binaries (default bin)
--with-db-type=TYPE     sort of database RT will use (default: mysql; others are
                        Oracle, Informix, Pg, SQLite)
--with-db-host=HOSTNAME FQDN of database server (default: localhost)
--with-db-port=PORT     port on which the database listens on
--with-db-rt-host=HOSTNAME
                        FQDN of database server (default: localhost)
--with-db-dba=DBA       name of database administrator (default: root)
--with-db-database=DBNAME
                        name of the database to use (default: rt3)
--with-db-rt-user=DBUSER
                        name of database user (default: rt_user)
--with-db-rt-pass=PASSWORD
                        password for database user (default: rt_pass)
--with-web-user=USER    user the web server runs as (default: www)
--with-web-group=GROUP  group the web server runs as (default: www)
--disable-option-checking  ignore unrecognized --enable/--with options
--disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
--enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
--enable-layout=LAYOUT  Use a specific directory layout (Default: relative)
--enable-devel-mode     Turn on development aids that might hurt you in production
--enable-graphviz       Turns on support for RT's GraphViz dependency charts
--enable-gd             Turns on support for RT's GD pie and bar charts
--enable-gpg            Turns on GNU Privacy Guard (GPG) support

Some influential environment variables:

PERL        Perl interpreter command

Use these variables to override the choices made by 'configure' or to help it to find libraries and programs with unusual names/locations.

Look at all the available flags and determine your RT install preferences, then

./configure (with the flags you want)

You might find it useful to put all your switches into a script in your build directory called build, so that if you need to run it more than once, or refer back to it, it's been saved somewhere. You can then do your build by merely typing

./build

3. Dependencies

After you build RT, but before you can run it, you must satisfy RT's myriad dependencies. RT makes use of many components external to the distributed package, and these must all be installed before the package will run. You must always do this step on install/update or upgrade actions.

First of all, check for compliance, using the CPAN-based dependency checker (if you have never run CPAN on this machine as this user, see below to manually initialize it first, or else :-):

make testdeps

or (the long way)

perl sbin/rt-test-dependencies --with-<databasename> --with-<web-environment>

Instead of <databasename>, type either mysql, postgres or oracle. Instead of <web-environment>, type either fastcgi, modperl1, or modperl2.

If there are unsatisfied dependencies (that is, if you are missing stuff), you will see complaints like "such-and-such not installed". Look carefully; these don't stand out that much. Go, ye, and fix dependencies. As root:

make fixdeps

or

perl sbin/rt-test-dependencies \
--with-<databasename> --with-<web-environment> --install

NOTE: If you have having difficulties with 'make fixdeps' due to errors like:

==> Couldn't mkdir '/root/.cpan/build/tmp': File exists           <==
             

NOTE: Some Perl Packages are using a build routine ( like DateTime modules) , but CPAN can't handle such routines based on build so you have to install this manually.

Set the following environment variable to tell fixdeps to invoke CPAN as a command line tool:

RT_FIX_DEPS_CMD='/usr/bin/perl -MCPAN -e"install %s"'

Make sure to export this variable with

export RT_FIX_DEPS_CMD

NOTE: if you've never run CPAN on your machine as the user whom you are building RT as, run it first or this part of the install will not be fun.

perl -MCPAN -e shell

You'll be walked through the configuration process. When you're done:

quit

NOTE: if things are still messed up, you are logged in as root, right?

Alternately, you could install missing items by hand. For example:

perl -MCPAN -e 'install DBD::mysql'

would install DBD::mysql.

NOTE: Some modules may require environment variables defined, for example Apache::Request.

NOTE: If you are using FastCGI, you will need to make sure that the FCGI module is installed. If not, run

perl -MCPAN -e 'install FCGI'

or something equivalent.

NOTE: If you are using RHEL5, you may end up with all sorts of errors. These can be fixed by installing Scalar::Util

perl -MCPAN -e 'install Scalar::Util'

Re-check to make sure everything was installed properly:

make testdeps

or

perl sbin/rt-test-dependencies --with-<databasename> --with-<web-environment>

NOTE: Some versions of the MIME::Tools package will not install cleanly. Specifically, MIME::Tools version 5.427 is missing a dependency that will not be installed automatically by the CPAN shell. It requires MIME::Base64 to be installed first. Otherwise, MIME::Entity will fail during testing and terminate the installation. Install MIME::Base64 explicitly, either manually or using:

# perl -MCPAN -e "install 'MIME::Base64'"
             
             

Thereafter, installing dependencies worked without further problems for me.

- Ed Eaglehouse

NOTE: graphviz dependencies can be met with packages from here: http://www.graphviz.org/Download..php. On CentOS 5.4, adding the repository provided by graphviz.org and doing

yum install graphviz graphviz-gd graphviz-devel

cleared up all related requirements. Installing additional packages via

yum install gd gd-devel

and

yum install expat expat-devel

Note: Ubuntu may throw a libgd error. Installing libgd2-xpm-dev by the below should fix the problem.

 apt-get -y install libgd2-xpm-dev build-essential

resolved all dependency problems. Doing 'make fixdeps' after a configure stage such as

./configure --with-web-handler=modperl2 --enable-graphviz --enable-gd --enable-gpg

completed with all dependencies met.

4. rt group

Create a new Unix group called 'rt' (or whatever you gave to the --with-rt-group option to the configure script).

5. For new installations only

If you're upgrading within the RT 3.x series, skip to step 6:

5.1 Init DB

As root and from within the rt build directory, type:

make install

Now you need to modify the installed [=etc/RT_SiteConfig.pm] to specify the connections to your DBMS engine (wtf shall I write here?!) and then type:

make initialize-database

For some database backends (MySQL at least) it is not able to create the database user. So you have to create that user beforehand and you have to give it rights for the database.

For MySQL with the default [=$DatabaseUser], [=$DatabaseName] and [=$DatabasePassword], do this SQL command (as root database user):

GRANT ALL PRIVILEGES ON rt4.* TO 'rt_user'@'localhost' IDENTIFIED BY 'rt_pass'

Replace the values 'rt4', 'rt_user', 'localhost' and 'rt_pass' by whatever is appropriate for you.

5.2 Drop DB if something goes wrong

If the make fails, type:

make dropdb

fix whatever's broken, and start over from step "init DB" step

5.3 if still failing...

If make install still fails, look in /etc/httpd/httpd.conf or /etc/httpd/conf/commonhttpd.conf (or wherever your httpd.conf is; this may vary by Unix distribution; locate httpd.conf may help) for a line that reads "Group <something>" and another that reads "User <somebody>"

Go to your RT source directory and type (without the brackets, substituting the right Group and User from the file you just looked at):

./configure --with-web-group=<something> --with-web-user=<somebody>

Skip to step 7.

5.4 initdb fails

The defaults were changed in PostgreSQL 8.1 and now tables are created without OIDs. One of workarounds is to add the following block at the top of etc/schema.Pg file:

--
-- Enforce OID creation for 8.1+
--
set default_with_oids = 't';

Once it's done "make initialize-database" will work perfectly.

-- Added by GalaxyMaster <galaxy at openwall.com>

6. For an Upgrade

For upgrading within the RT 3.x series - if you are not upgrading or have already completed step 5, skip to step 7.

As root, type:

make upgrade

(replace "make" with the local name for Make, if you need to)

This will build new executable files, config files and libraries without overwriting your RT database.

It may then instruct you to update your RT system database objects

7. Configuration

Edit [=etc/RT_SiteConfig.pm] in your RT installation directory, by specifying any values you need to change from the defaults as defined in RT_Config.pm. It is easiest to do this by copying RT_Config.pm to RT_SiteConfig.pm, and then uncommenting and changing anything you need to set, though perhaps this isn't quite the best approach.

In many cases sensible defaults have been included. In others, you must supply a value. Some values (such as the RT log directory) will come from values you supplied in the Makefile. You'll find further explanation inline in the RT_SiteConfig.pm file. You should look at and consider changing the following entries:

$DatabasePassword = 'rt_pass'

which is the password the DatabaseUser should use to access the database.

NOTE: Some MySQL users have had trouble with passwords of longer than 8 characters; if you cannot connect, try a password of 8 characters or fewer.

$CanonicalizeEmailAddressMatch = 'subdomain.example.com$';
$CanonicalizeEmailAddressReplace = 'example.com';

The $CanonicalizeEmailAddress variables allow you to keep incoming messages consistent, such as when a site removes the subdomain from an email address. In the example presented by the defaults, if messages from your organization sometimes come from exchange.example.com and sometimes from example.com, you'd set $CanonicalizeEmailAddressMatch to exchange.example.com and $CanonicalizeEmailAddressReplace to example.com

$SenderMustExistInExternalDatabase = undef;

If $SenderMustExistInExternalDatabase is true, RT will refuse to auto-create non-staff accounts for unknown users filing new tickets by email if you are using the "LookupSenderInExternalDatabase" option elsewhere in RT_SiteConfig.pm. Instead, an error message will be returned and RT will forward the user's message to $RTOwner as defined in RT_SiteConfig.pm. If you are not using $LookupSenderInExternalDatabase, this option has no effect. If you define an AutoRejectRequest template, RT will use this template for the rejection message.

$CorrespondAddress = 'RT::CorrespondAddress.not.set';
$CommentAddress = 'RT::CommentAddress.not.set';

$CorrespondAddress and $CommentAddress are the default addresses that will be listed in both From: and Reply-To: headers of reply and comment mail, respectively, sent by RT, unless they are overridden by a queue-specific address.

$MailCommand = 'sendmailpipe';

$MailCommand defines which method RT will use to try to send mail. We know sendmailpipe works fairly well. If sendmailpipe doesn't work well for you, try sendmail. Note that you should remove the '-t' from $SendmailArguments if you use sendmail rather than sendmailpipe. Also note that sendmailpipe and sendmail aren't the names of commands on your system, but instructions that tell RT what mail delivery subsystem to try.

• Don't forget to restart the Apache webserver after doing changes in RT_SiteConfig.pm!* This is true of any change, but we mention it here since this is the configuration option you're most likely to have to experiment with.

$SendmailArguments = "-oi -t";

$SendmailArguments defines what flags to pass to $Sendmail, assuming you picked sendmail or sendmailpipe as the $MailCommand. If you picked sendmailpipe, then $SendmailArguments must include the "-t" flag. The default options are good for most sendmail wrappers and workalikes.

$SendmailPath = "/usr/sbin/sendmail";

If you selected sendmailpipe as $MailCommand, you must specify the path to your sendmail executable file in $SendmailPath. If you did not select sendmailpipe this has no effect.

In case of Exim, the following configuration works:

Set($MailCommand , 'sendmail');
Set($SendmailArguments , "-bm -- <your email address>");
Set($SendmailPath, "/usr/sbin/exim4");
Set($NotifyActor, 1);

$Timezone = 'US/Eastern';

$Timezone is used to convert times entered by users into GMT and back again. It should be set to a timezone recognized by your local Unix box, and -- in general -- you should pick the timezone the majority of your users reside in.

$UseFriendlyToLine = 0;

RT can set a "friendly", rather than blank, To: header when sending messages to Ccs or AdminCcs. This feature does not work with Sendmail(tm)-brand sendmail. If you are using sendmail, rather than postfix, qmail, exim, or some other program, you must disable this option (by setting it to 0 rather than 1).

$WebPath = "";

A variable used to help RT construct URLs that point back to RT. If you've put RT somewhere other than at the root of your webserver, you need to define a WebPath. RT uses this in the construction of relative URLs. $WebPath requires a leading / but no trailing /

Example: if your installation is at

http://www.fsck.com/rt/

set this to "/rt".

$WebBaseURL = "http://not.configured:80";

A variable used to help RT construct URLs that point back to RT. $WebBaseURL is the base of the URL. it should usually include the scheme, the host, and the port if non-standard.

Example: "https://fsck.com" or "http://fsck.com:88"

$WebBaseURL doesn't need a trailing /

$WebURL = $WebBaseURL . $WebPath . "/";

A variable used to help RT construct URLs that point back to RT. [=$WebURL] is the combination of [=$WebBaseURL] and [=$WebPath]. Generally, you shouldn't change it.

$WebImagesURL = $WebURL . "/NoAuth/images/";

[=$WebImagesURL] points to the base URL where RT can find its images. If you're running the FastCGI version of the RT web interface, you should make RT's [=WebRT/html/NoAuth/images] directory available on a static web server and supply that URL as [=$WebImagesUrl] -- alternately, you can tell Apache not to run it through FastCGI.

THEN

Configure web server, read ManualApacheConfig

---

Prev: ManualRequirements --- Up: UserManual --- Next: ManualApacheConfig