Difference between revisions of "GentooInstallGuide"

From Request Tracker Wiki
Jump to navigation Jump to search
m (12 revisions imported)
 
(8 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
== Intro ==
 
== Intro ==
  
Please direct all questions about this guide to <code>rl03 -at- gentoo -dot- org</code>.
+
Latest version available through Portage: '''<code>rt-4.0.5</code>'''
  
Latest version available through Portage: *<code>rt-3.6.7</code>*
+
Tested on a new basic hardened install on amd64 March 12, 2012.
  
 
This guide uses virtual hosting. Virtual [http://www.uk2.net/web-hosting/ hosting] means that you can give the appearance of running several servers while using only one machine. If your machine is going to be used only for RT, then you may use this guide as is; the fact that you are using virtual hosting will not be a conflict. However, if your machine is going to be used for other things in addition to RT, and you are not familiar with virtual hosting, you should probably check out Apache's documentation on [http://httpd.apache.org/docs/vhosts/ Virtual Hosts].
 
This guide uses virtual hosting. Virtual [http://www.uk2.net/web-hosting/ hosting] means that you can give the appearance of running several servers while using only one machine. If your machine is going to be used only for RT, then you may use this guide as is; the fact that you are using virtual hosting will not be a conflict. However, if your machine is going to be used for other things in addition to RT, and you are not familiar with virtual hosting, you should probably check out Apache's documentation on [http://httpd.apache.org/docs/vhosts/ Virtual Hosts].
  
 
'''Note''': This version of the guide assumes that you have updated your Apache installation per [http://www.gentoo.org/doc/en/apache-upgrading.xml this document]. This is not needed on a brand new install of apache.
 
'''Note''': This version of the guide assumes that you have updated your Apache installation per [http://www.gentoo.org/doc/en/apache-upgrading.xml this document]. This is not needed on a brand new install of apache.
 +
==Installation==
  
Turn on the <code>vhosts</code> flag for <code>rt</code>. If the <code>vhosts</code> flag is disabled, *<code>webapp-config</code>* will be run automatically.
+
Turn on the <code>vhosts</code> flag for <code>rt</code>. If the <code>vhosts</code> flag is disabled, <code>webapp-config</code> will be run automatically.
  
  echo "www-apps/rt vhosts" &gt;&gt; /etc/portage/package.use
+
  # echo "www-apps/rt vhosts" &gt;&gt; /etc/portage/package.use
 +
You also need either MySQL or PostgreSQL, so add that to the package use if not already a global use flag.
 +
# echo "www-apps/rt mysql" >> /etc/portage/package.use
 +
or
  
'''Note''': It is important that you use a recent webapp-config (&gt;=1.50.10) in order to avoid a broken vhosts configuration.
+
# echo "www-apps/rt postgres" >> /etc/portage/package.use
 +
The above can be combined into one line.
  
echo "app-admin/webapp-config" &gt;&gt; /etc/portage/package.keywords
+
To install, enter
  
== Installation ==
+
# emerge -av --autounmask-write=y --backtrack=30 rt
 +
It will give a huge list of needed keyword, mask, and USE changes necessary. Verify the USE flags you want are set. Press enter to accept and then
 +
# <code>etc-update</code>
 +
Then run the emerge command again. This will pull in MySQL or PostgreSQL and Apache if not already installed.
  
To install, simply type
+
Don't forget to run <code>etc-update</code> or <code>dispatch-conf</code>
 
 
emerge rt
 
 
 
 
Don't forget to run *<code>etc-update</code>* or *<code>dispatch-conf</code>*
 
 
 
Note: You may need to edit <code>/etc/portage/package.keywords</code> and add a few dependencies. Others may be needed depending on your USE flags.
 
 
 
<nowiki># www-apps/rt dependencies
 
www-apps/rt
 
dev-perl/Params-Validate
 
dev-perl/Cache-Cache
 
dev-perl/Exception-Class
 
dev-perl/HTML-Mason
 
dev-perl/MLDBM
 
dev-perl/FreezeThaw
 
dev-perl/Apache-Session
 
dev-perl/XML-RSS
 
dev-perl/HTTP-Server-Simple
 
dev-perl/HTTP-Server-Simple-Mason
 
dev-perl/GD
 
dev-perl/GDGraph
 
dev-perl/GDTextUtil
 
dev-perl/Text-WikiFormat
 
dev-perl/HTML-Tree
 
dev-perl/HTML-Format
 
dev-perl/libwww-perl
 
dev-perl/Calendar-Simple
 
dev-perl/DBI
 
dev-perl/Test-Inline
 
dev-perl/class-returnvalue
 
dev-perl/dbix-searchbuilder
 
dev-perl/text-template
 
dev-perl/HTML-Parser
 
dev-perl/HTML-Scrubber
 
dev-perl/log-dispatch
 
dev-perl/locale-maketext-lexicon
 
dev-perl/locale-maketext-fuzzy
 
dev-perl/MIME-tools
 
dev-perl/MailTools
 
dev-perl/text-wrapper
 
dev-perl/Time-modules
 
dev-perl/TermReadKey
 
dev-perl/text-autoformat
 
dev-perl/Text-Quoted
 
dev-perl/Tree-Simple
 
dev-perl/Module-Versions-Report
 
dev-perl/Cache-Simple-TimedExpiry
 
dev-perl/XML-Simple
 
dev-perl/regexp-common
 
 
 
</nowiki>
 
  
 
Since we are installing RT into a virtual host, we will need to symlink/copy our installation into our <code>/var</code> folder. This guide will use '''myrt''' as the hostname.
 
Since we are installing RT into a virtual host, we will need to symlink/copy our installation into our <code>/var</code> folder. This guide will use '''myrt''' as the hostname.
  
  webapp-config -I -h myrt -d rt rt 3.6.1
+
  # webapp-config -I -h myrt -d rt rt 4.0.5
  
 
== Database Setup ==
 
== Database Setup ==
  
RT provides a script called *<code>rt-setup-database</code>* which creates the initial database for you. Please note that *<code>rt-setup-database</code>* does NOT create a database '''user''' for you. If you have not already created a database user for RT, please consult the appropriate documentation, such as [[ConfigureMysqlOnGentoo]].
+
RT provides a script called <code>rt-setup-database</code> which creates the initial database for you. Please note that <code>rt-setup-database</code> does '''not''' create a database ''user'' for you. If you have not already created a database user for RT, please consult the appropriate documentation, such as [[ConfigureMysqlOnGentoo]].
 
 
* For MySQL:
 
 
 
Note: If you did not previously have mysql installed, you will need to [[ConfigureMysqlOnGentoo]].
 
 
 
Verify that the <code>skip-innodb</code> is commented out in <code>/etc/mysql/my.cnf</code>. If it is not, then put an octothorpe in front of it:
 
 
 
<nowiki>.
 
.
 
[mysqld]
 
#skip-innodb
 
user          = mysql
 
.
 
.
 
 
</nowiki>
 
 
 
and restart the <code>mysql</code> server:
 
 
 
/etc/init.d/mysql restart
 
 
  
Then set up the database:
+
====MySQL:====
  
/var/www/myrt/rt-3.6.1/sbin/rt-setup-database --action init --dba root --prompt-for-dba-password
+
If you did not previously have mysql installed, you will need to [[ConfigureMysqlOnGentoo]].
  
* For PostgreSQL:
+
====PostgreSQL (untested in current update of this document):====
  
  /var/www/myrt/rt-3.6.1/sbin/rt-setup-database --action init --dba postgres --prompt-for-dba-password
+
  # /var/www/myrt/rt-4.0.5/sbin/rt-setup-database --action init --dba postgres --prompt-for-dba-password
 
 
  
 
For this to work, [[PostgreSQL]] may need to listen on TCP 5432. In your <code>postgresql.conf</code>, set
 
For this to work, [[PostgreSQL]] may need to listen on TCP 5432. In your <code>postgresql.conf</code>, set
Line 123: Line 55:
 
== Configure RT ==
 
== Configure RT ==
  
After installing RT into the virtual host, you will need to configure RT. RT uses an overlay system for configuration. On Gentoo, the default configuration will be at *[=/var/www/myrt/rt-3.6.1/etc/[[RT Config|RT_Config]].pm]*, and the site-specific configuration will be at *[=/var/www/myrt/rt-3.6.1/etc/[[RT SiteConfig|RT_SiteConfig]].pm]*. I would recommend copying [=[[RT Config|RT_Config]].pm] over to [=[[RT SiteConfig|RT_SiteConfig]].pm], and modifying all of the settings in [=[[RT SiteConfig|RT_SiteConfig]].pm].
+
After installing RT into the virtual host, you will need to configure RT. RT uses an overlay system for configuration. On Gentoo, the default configuration will be at <code>/var/www/myrt/rt-4.0.5/etc/[[RT Config|RT_Config]].pm</code>, and the site-specific configuration will be at <code>/var/www/myrt/rt-4.0.5/etc/[[RT SiteConfig|RT_SiteConfig]].pm</code>. I would recommend copying <code>RT_Config.pm</code> over to <code>RT_SiteConfig.pm (which does not get installed)</code>, and modifying all of the settings in <code>RT_SiteConfig.pm</code>.
  
  cd /var/www/myrt/rt-3.6.1/etc
+
  # cd /var/www/myrt/rt-4.0.5/etc
  cp RT_Config.pm RT_SiteConfig.pm
+
  # cp RT_Config.pm RT_SiteConfig.pm
  nano RT_SiteConfig.pm
+
  # $EDITOR RT_SiteConfig.pm
 
  
 
You should set [[WebSessionClass]] to Apache::Session::File if you plan to use internal authentication.
 
You should set [[WebSessionClass]] to Apache::Session::File if you plan to use internal authentication.
  
Now you need to set up your database connection, web location, email gateway, etc. Please consult [[ManualInstallation]].
+
Now you need to set up your database connection, web location, email gateway, etc. Please consult section 7. Configuration of [[ManualInstallation]].
  
 
== Configure Webserver ==
 
== Configure Webserver ==
  
=== Apache1 ===
+
=== Apache2 ===
 
+
Note: Additional information may be found in [[ManualApacheConfig]].
==== mod_perl ====
 
 
 
RT comes with a Gentoo-specific Apache1 configuration file. It can be found in <code>/var/www/myrt/rt-3.6.1/etc/rt_apache.conf</code>
 
 
 
Copy it to the Apache vhosts directory and edit to set <code>MY_RT_DOMAIN</code> and [=[[ServerAdmin]]]:
 
 
 
cp /var/www/myrt/rt-3.4.5/etc/rt_apache.conf /etc/apache/vhosts.d/
 
vim /etc/apache/vhosts.d/rt_apache.conf
 
 
 
 
Now, let's make sure <code>mod_perl</code> is turned on. Edit <code>/etc/apache/modules.d/10-mod_perl.conf</code> and make sure it contains the following:
 
 
 
&lt;IfDefine PERL&gt;
 
  LoadModule perl_module    /usr/lib/apache-extramodules/libperl.so
 
&lt;/IfDefine&gt;
 
 
 
 
Edit <code>/etc/conf.d/apache</code> to instruct <code>apache</code> to start with <code>PERL</code> and enabled.
 
 
 
APACHE_OPTS="-D PERL"
 
 
 
==== mod_fastcgi ====
 
 
 
NOTE: If you wish to use <code>mod_fastcgi</code>, you need to instruct <code>webapp-config</code> to install <code>rt</code> with appropriate permissions. Edit <code>/etc/vhosts/webapp-config</code>:
 
 
 
VHOST_DEFAULT_UID="rt"
 
VHOST_DEFAULT_GID="rt"
 
 
 
 
RT comes with a Gentoo-specific Apache1 configuration file. It can be found in <code>/var/www/myrt/rt-3.6.1/etc/rt_apache1_fcgi.conf</code>
 
 
 
Copy it to the Apache vhosts directory and edit to set <code>MY_RT_DOMAIN</code> and [=[[ServerAdmin]]]:
 
 
 
cp /var/www/myrt/rt-3.6.1/etc/rt_apache1_fcgi.conf /etc/apache/vhosts.d/
 
nano /etc/apache/vhosts.d/rt_apache1_fcgi.conf
 
 
 
 
Edit <code>/etc/conf.d/apache</code> to instruct <code>apache</code> to start with <code>FASTCGI</code> and enabled.
 
 
 
APACHE_OPTS="-D FASTCGI"
 
 
  
If this is your first time installing apache, you will want it to start on bootup.
 
  
rc-update add apache default
+
====mod_perl====
 
 
 
Restart apache so that all changes made so far will take effect.
 
 
 
/etc/init.d/apache restart
 
 
 
 
=== Apache2 ===
 
 
 
==== mod_perl ====
 
  
 
As of rt-3.4.4, mod_perl2 is supported.
 
As of rt-3.4.4, mod_perl2 is supported.
  
RT comes with a Gentoo-specific Apache2 configuration file. It can be found in <code>/var/www/myrt/rt-3.6.1/etc/rt_apache2.conf</code>
+
Save the following to "/etc/apache2/vhosts.d/rt_apache2.conf", replacing MY_RT_DOMAIN and MY_EMAIL_ADDRESS.
 
 
Copy it to the Apache vhosts directory and edit to set <code>MY_RT_DOMAIN</code> and [=[[ServerAdmin]]]:
 
  
  cp /var/www/myrt/rt-3.6.1/etc/rt_apache2.conf /etc/apache2/vhosts.d/
+
  <VirtualHost MY_RT_DOMAIN:80>
vim /etc/apache2/vhosts.d/rt_apache2.conf
+
    ServerAdmin MY_EMAIL_ADDRESS
 +
    # the following line might need to be uncommented:
 +
    #LoadModule perl_module modules/mod_perl.so
 +
    ### Optional apache logs for RT
 +
    #ErrorLog /var/www/myrt/rt-4.0.5/var/log/apache2.error
 +
    #TransferLog /var/www/myrt/rt-4.0.5/var/log/apache2.access
 +
    #LogLevel debug
 
   
 
   
 
+
    AddDefaultCharset UTF-8
NOTE: -As of 12/09/2005 there is a gotcha in <code>/var/www/myrt/rt-3.6.1/etc/rt_apache2.conf</code>. When using mod_perl2 then you need to change: [[PerlModule]] Apache::DBI to [[PerlModule]] Apache2::DBI- This should not be necessary with a properly configured mod_perl2.
 
 
 
NOTE: Also consider specifying the actual path of your perl modules on the [=[[PerlSetEnv]]] line. For details about [=[[PerlSetEnv]]] go to [http://perl.apache.org/docs/1.0/guide/porting.html#_INC_and_mod_perl =].
 
 
 
  &lt;Location /&gt;
 
    ............
 
    PerlHandler RT::Mason
 
    PerlSetEnv PERL5LIB /usr/lib/perl5/vendor_perl/5.8.7:/usr/lib/perl5/5.8.7
 
    ............
 
&lt;/Location&gt;
 
 
   
 
   
 +
    DocumentRoot "/var/www/myrt/htdocs/rt"
 +
    <Location />
 +
        Order allow,deny
 +
        Allow from all
 +
        SetHandler modperl
 +
        PerlResponseHandler Plack::Handler::Apache2
 +
        PerlSetVar psgi_app /var/www/myrt/rt-4.0.5/sbin/rt-server
 +
    </Location>
 +
    <Perl>
 +
        use Plack::Handler::Apache2;
 +
        Plack::Handler::Apache2->preload("/var/www/myrt/rt-4.0.5/sbin/rt-server");
 +
    </Perl>
 +
</VirtualHost>
  
Edit <code>/etc/conf.d/apache2</code> to instruct <code>apache</code> to start with <code>PERL</code> and enabled.
+
Edit <code>/etc/conf.d/apache2</code> to instruct <code>apache</code> to start with <code>PERL</code> enabled.
  
  APACHE2_OPTS="-D PERL"
+
  APACHE2_OPTS="[other options] -D PERL"
 
  
 
NOTE: you may need to
 
NOTE: you may need to
  
  chown -R apache:apache /var/www/myrt/rt-3.6.1/var
+
  chown -R apache:apache /var/www/myrt/rt-4.0.5/var
  
==== mod_fastcgi ====
+
==== mod_fastcgi (outdated instructions) ====
  
 
NOTE: If you wish to use <code>mod_fastcgi</code>, you need to instruct <code>webapp-config</code> to install <code>rt</code> with appropriate permissions. Edit <code>/etc/vhosts/webapp-config</code>:
 
NOTE: If you wish to use <code>mod_fastcgi</code>, you need to instruct <code>webapp-config</code> to install <code>rt</code> with appropriate permissions. Edit <code>/etc/vhosts/webapp-config</code>:
Line 231: Line 116:
 
  VHOST_DEFAULT_UID="rt"
 
  VHOST_DEFAULT_UID="rt"
 
  VHOST_DEFAULT_GID="rt"
 
  VHOST_DEFAULT_GID="rt"
 
  
 
RT comes with a Gentoo-specific Apache2 configuration file. It can be found in <code>/var/www/myrt/rt-3.6.1/etc/rt_apache2_fcgi.conf</code>
 
RT comes with a Gentoo-specific Apache2 configuration file. It can be found in <code>/var/www/myrt/rt-3.6.1/etc/rt_apache2_fcgi.conf</code>
Line 239: Line 123:
 
  cp /var/www/myrt/rt-3.6.1/etc/rt_apache2_fcgi.conf /etc/apache2/vhosts.d/
 
  cp /var/www/myrt/rt-3.6.1/etc/rt_apache2_fcgi.conf /etc/apache2/vhosts.d/
 
  vim /etc/apache2/vhosts.d/rt_apache2_fcgi.conf
 
  vim /etc/apache2/vhosts.d/rt_apache2_fcgi.conf
 
  
 
Edit <code>/etc/conf.d/apache2</code> to instruct <code>apache2</code> to start with <code>FASTCGI</code> and enabled.
 
Edit <code>/etc/conf.d/apache2</code> to instruct <code>apache2</code> to start with <code>FASTCGI</code> and enabled.
  
 
  APACHE2_OPTS="-D FASTCGI"
 
  APACHE2_OPTS="-D FASTCGI"
 
  
 
If this is your first time installing apache, you will want it to start on bootup.
 
If this is your first time installing apache, you will want it to start on bootup.
  
 
  rc-update add apache2 default
 
  rc-update add apache2 default
 
  
 
Restart apache so that all changes made so far will take effect.
 
Restart apache so that all changes made so far will take effect.
Line 255: Line 136:
 
  /etc/init.d/apache2 restart
 
  /etc/init.d/apache2 restart
  
=== lighttpd ===
+
=== lighttpd (untested) ===
  
 
You can run RT on <code>lighttpd</code> + <code>fastcgi</code>. The ebuild will install an initscript <code>/etc/init.d/rt</code> and a config file <code>/etc/conf.d/rt</code>.
 
You can run RT on <code>lighttpd</code> + <code>fastcgi</code>. The ebuild will install an initscript <code>/etc/init.d/rt</code> and a config file <code>/etc/conf.d/rt</code>.
Line 263: Line 144:
 
  VHOST_DEFAULT_UID="rt"
 
  VHOST_DEFAULT_UID="rt"
 
  VHOST_DEFAULT_GID="rt"
 
  VHOST_DEFAULT_GID="rt"
 
  
 
You will need to edit <code>/etc/conf.d/rt</code> to set [[RTPATH]] to the root of your installation. You shouldn't need to edit anything else in that file.
 
You will need to edit <code>/etc/conf.d/rt</code> to set [[RTPATH]] to the root of your installation. You shouldn't need to edit anything else in that file.
Line 283: Line 163:
 
  )
 
  )
 
  )
 
  )
 
  
 
Be sure to set the correct path to socket (same as <code>$FCGI_SOCKET_PATH</code> in <code>/etc/conf.d/rt</code>).
 
Be sure to set the correct path to socket (same as <code>$FCGI_SOCKET_PATH</code> in <code>/etc/conf.d/rt</code>).
Line 291: Line 170:
 
  /etc/init.d/rt start
 
  /etc/init.d/rt start
 
  /etc/init.d/lighttpd start
 
  /etc/init.d/lighttpd start
 
  
 
If things don't seem to be working, check the <code>lighttpd</code> logs in <code>/var/log/lighttpd</code> and edit <code>/etc/init.d/rt</code> as per the comments in the file to make the <code>rt</code> daemon more verbose.
 
If things don't seem to be working, check the <code>lighttpd</code> logs in <code>/var/log/lighttpd</code> and edit <code>/etc/init.d/rt</code> as per the comments in the file to make the <code>rt</code> daemon more verbose.
Line 302: Line 180:
  
 
= Comments, questions, problems =
 
= Comments, questions, problems =
 
+
Upgrades (old but likley still relevant)
== Missing dependencies? ==
 
 
 
Q: There's some dependencies not mentioned in this guide, that also need to be installed, I installed these as well to get it running: dev-perl/dbix-searchbuilder dev-perl/DBI dev-perl/[[DBIx]]-[[DBSchema]] dev-perl/[[DBIx]]-[[ContextualFetch]]. Could someone please post exact versions of these additional CPAN requirements in a working installation?
 
 
 
A: The first two are pulled in by the ebuild; the last two are not required (according to the docs).
 
 
 
== Out of memory! / Callback called exit ==
 
 
 
Q: I'm having problems after following this guide. I succeeded in seeing the login screen once, but was not able to log in. At subsequent requests, the apache error log just gives me:
 
 
 
Out of memory!
 
Callback called exit.
 
 
 
 
I tried the users list, seems others are also having a similar problem:
 
 
 
Hello Steffen,
 
 
have the same issue. Tested with debian with out this issue. Seems to be a
 
gentoo only issue. You can find some email about this issue. I have no idea
 
till now.
 
Even last comment to try running apache with mpm_worker is not solving the
 
issue.
 
 
Thanks,
 
Thomas
 
 
On Thursday 06 April 2006 13:44, Steffen Poulsen wrote:
 
 
&gt;&gt; Thomas Knoezinger wrote:
 
&gt;
 
&gt;&gt;&gt; &gt;P.S: Please let me know if you installation of rt is eating a lot of
 
&gt;&gt;&gt; &gt; memory even for prompting login page.
 
&gt;
 
&gt;&gt;
 
&gt;&gt; Seems like it's finally getting to run, after mason was compiled for
 
&gt;&gt; modperl support  :-)
 
&gt;&gt;
 
&gt;&gt; But you're right, it only managed to show the login-page once -
 
&gt;&gt; subsequent requests just puts this in apache error log:
 
&gt;&gt;
 
&gt;&gt; Out of memory!
 
&gt;&gt; Callback called exit.
 
&gt;&gt;
 
&gt;&gt; Any ideas?
 
&gt;&gt;
 
&gt;&gt; // Steffen, Denmark
 
 
 
 
Looking forward to see this baby run with Gentoo, hope you can help! :-)
 
 
 
// Steffen
 
 
 
Installing an earlier version of DBD-mysql got me past the login screen.
 
 
 
<nowiki># emerge -p --oneshot =DBD-mysql-3.0002
 
 
</nowiki>
 
 
 
If this helps other as well, it might be helpful to have it added to the version requirements.
 
 
 
// Steffen
 
 
 
A: Please file a bug on bugs.gentoo.org
 
 
 
== Update ==
 
 
 
Using the SQL provided here ( http://lists.fsck.com/pipermail/rt-users/2006-July/040410.html ), it seems to have solved the <code>Out of memory / Callback called exit</code> errors. Works with newest available DBD-mysql (DBD-mysql-3.0008) and mysql version 5.0.22-log.
 
 
 
== mysql 4.1 ==
 
 
 
Q: Finally got this semi-working with mysql 4.1 by editing the links section of the schema file and specifying a latin charset. Now I have a "functioning" system, but the session variable doesn't seem to work. You have to log back in after every link you click. If anyone's beaten this, please let me know. clifford -atta- clevergeek.com
 
 
 
A: See http://bugs.gentoo.org/show_bug.cgi?id=131399
 
 
 
== Upgrades ==
 
  
 
3.6.1 is out in portage! Can anyone provide some advice on how to upgrade from 3.6.0 to 3.6.1 in gentoo?
 
3.6.1 is out in portage! Can anyone provide some advice on how to upgrade from 3.6.0 to 3.6.1 in gentoo?
  
/Normally/ this should just be as easy as "webapp-config -U -h rt.domain.foo rt 3.6.1". However, the problem here is that none of the ebuilds follow a common structure. eg, some of them install the RT html data into the htdocs, some install into the default hostroot/rt/share/html. It also looks like somewhere along the line someone's changed the default install prefix from hostroot/rt to hostroot/rt-version, so 3.6.1 will install to hostroot/rt-3.6.1 -- [[TomLanyon]]
+
''Normally'' this should just be as easy as webapp-config -U -h rt.domain.foo rt 3.6.1. However, the problem here is that none of the ebuilds follow a common structure. eg, some of them install the RT html data into the htdocs, some install into the default hostroot/rt/share/html. It also looks like somewhere along the line someone's changed the default install prefix from hostroot/rt to hostroot/rt-version, so 3.6.1 will install to hostroot/rt-3.6.1 -- [[TomLanyon]]

Latest revision as of 15:11, 6 April 2016


Unofficial Installation Guide

This is an unofficial installation guide. It may be outdated or apply only to very specific configurations and versions. The official and maintained installation steps for RT are in the README and UPGRADING documents included in the official .tar.gz packages.

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.


Installing RT in Gentoo

Intro

Latest version available through Portage: rt-4.0.5

Tested on a new basic hardened install on amd64 March 12, 2012.

This guide uses virtual hosting. Virtual hosting means that you can give the appearance of running several servers while using only one machine. If your machine is going to be used only for RT, then you may use this guide as is; the fact that you are using virtual hosting will not be a conflict. However, if your machine is going to be used for other things in addition to RT, and you are not familiar with virtual hosting, you should probably check out Apache's documentation on Virtual Hosts.

Note: This version of the guide assumes that you have updated your Apache installation per this document. This is not needed on a brand new install of apache.

Installation

Turn on the vhosts flag for rt. If the vhosts flag is disabled, webapp-config will be run automatically.

  1. echo "www-apps/rt vhosts" >> /etc/portage/package.use

You also need either MySQL or PostgreSQL, so add that to the package use if not already a global use flag.

# echo "www-apps/rt mysql" >> /etc/portage/package.use

or

  1. echo "www-apps/rt postgres" >> /etc/portage/package.use

The above can be combined into one line.

To install, enter

  1. emerge -av --autounmask-write=y --backtrack=30 rt

It will give a huge list of needed keyword, mask, and USE changes necessary. Verify the USE flags you want are set. Press enter to accept and then

# etc-update

Then run the emerge command again. This will pull in MySQL or PostgreSQL and Apache if not already installed.

Don't forget to run etc-update or dispatch-conf

Since we are installing RT into a virtual host, we will need to symlink/copy our installation into our /var folder. This guide will use myrt as the hostname.

  1. webapp-config -I -h myrt -d rt rt 4.0.5

Database Setup

RT provides a script called rt-setup-database which creates the initial database for you. Please note that rt-setup-database does not create a database user for you. If you have not already created a database user for RT, please consult the appropriate documentation, such as ConfigureMysqlOnGentoo.

MySQL:

If you did not previously have mysql installed, you will need to ConfigureMysqlOnGentoo.

PostgreSQL (untested in current update of this document):

  1. /var/www/myrt/rt-4.0.5/sbin/rt-setup-database --action init --dba postgres --prompt-for-dba-password

For this to work, PostgreSQL may need to listen on TCP 5432. In your postgresql.conf, set

listen_addresses = 'localhost', port = 5432

Configure RT

After installing RT into the virtual host, you will need to configure RT. RT uses an overlay system for configuration. On Gentoo, the default configuration will be at /var/www/myrt/rt-4.0.5/etc/RT_Config.pm, and the site-specific configuration will be at /var/www/myrt/rt-4.0.5/etc/RT_SiteConfig.pm. I would recommend copying RT_Config.pm over to RT_SiteConfig.pm (which does not get installed), and modifying all of the settings in RT_SiteConfig.pm.

  1. cd /var/www/myrt/rt-4.0.5/etc
# cp RT_Config.pm RT_SiteConfig.pm
# $EDITOR RT_SiteConfig.pm

You should set WebSessionClass to Apache::Session::File if you plan to use internal authentication.

Now you need to set up your database connection, web location, email gateway, etc. Please consult section 7. Configuration of ManualInstallation.

Configure Webserver

Apache2

Note: Additional information may be found in ManualApacheConfig.

mod_perl

As of rt-3.4.4, mod_perl2 is supported.

Save the following to "/etc/apache2/vhosts.d/rt_apache2.conf", replacing MY_RT_DOMAIN and MY_EMAIL_ADDRESS.

    ServerAdmin MY_EMAIL_ADDRESS
    # the following line might need to be uncommented:
    #LoadModule perl_module modules/mod_perl.so
    ### Optional apache logs for RT
    #ErrorLog /var/www/myrt/rt-4.0.5/var/log/apache2.error
    #TransferLog /var/www/myrt/rt-4.0.5/var/log/apache2.access
    #LogLevel debug
 AddDefaultCharset UTF-8

 DocumentRoot "/var/www/myrt/htdocs/rt"
 <Location />
     Order allow,deny
     Allow from all
     SetHandler modperl
     PerlResponseHandler Plack::Handler::Apache2
     PerlSetVar psgi_app /var/www/myrt/rt-4.0.5/sbin/rt-server
 </Location>
 <Perl>
     use Plack::Handler::Apache2;
     Plack::Handler::Apache2->preload("/var/www/myrt/rt-4.0.5/sbin/rt-server");
 </Perl>

Edit /etc/conf.d/apache2 to instruct apache to start with PERL enabled.

APACHE2_OPTS="[other options] -D PERL"

NOTE: you may need to

chown -R apache:apache /var/www/myrt/rt-4.0.5/var

mod_fastcgi (outdated instructions)

NOTE: If you wish to use mod_fastcgi, you need to instruct webapp-config to install rt with appropriate permissions. Edit /etc/vhosts/webapp-config:

VHOST_DEFAULT_UID="rt"

VHOST_DEFAULT_GID="rt"

RT comes with a Gentoo-specific Apache2 configuration file. It can be found in /var/www/myrt/rt-3.6.1/etc/rt_apache2_fcgi.conf

Copy it to the Apache vhosts directory and edit to set MY_RT_DOMAIN and [=ServerAdmin]:

cp /var/www/myrt/rt-3.6.1/etc/rt_apache2_fcgi.conf /etc/apache2/vhosts.d/

vim /etc/apache2/vhosts.d/rt_apache2_fcgi.conf

Edit /etc/conf.d/apache2 to instruct apache2 to start with FASTCGI and enabled.

APACHE2_OPTS="-D FASTCGI"

If this is your first time installing apache, you will want it to start on bootup.

rc-update add apache2 default

Restart apache so that all changes made so far will take effect.

/etc/init.d/apache2 restart

lighttpd (untested)

You can run RT on lighttpd + fastcgi. The ebuild will install an initscript /etc/init.d/rt and a config file /etc/conf.d/rt.

NOTE: If you wish to use mod_fastcgi, you need to instruct webapp-config to install rt with appropriate permissions. Edit /etc/vhosts/webapp-config:

VHOST_DEFAULT_UID="rt"

VHOST_DEFAULT_GID="rt"

You will need to edit /etc/conf.d/rt to set RTPATH to the root of your installation. You shouldn't need to edit anything else in that file.

Also note that, under the default configuration, the socket in $FCGI_SOCKET_PATH is owned by rt:lighttpd, and is chmod-ded to g+rwx. This means that user lighttpd needs to be in the rt group. One way to do that is to use vigr. If you don't like that, edit /etc/init.d/rt to suit your needs.

You will also need to edit /etc/lighttpd.conf to enable mod_fastcgi.

  • Uncomment mod_fastcgi under server.modules
  • set server.document-root
  • set fastcgi.server to something like this: fastcgi.server = ( "/rt" => ( "rt" => ( "socket" => "/var/www/localhost/rt-3.6.1/var/appSocket", "check-local" => "disable" ) ) )

Be sure to set the correct path to socket (same as $FCGI_SOCKET_PATH in /etc/conf.d/rt).

Now, start rt and lighttpd:

/etc/init.d/rt start

/etc/init.d/lighttpd start

If things don't seem to be working, check the lighttpd logs in /var/log/lighttpd and edit /etc/init.d/rt as per the comments in the file to make the rt daemon more verbose.

Note: you should be able to use this initscript with any fastcgi-enabled webserver. Please send me an email if you get rt to work with any other webserver.

Log in

Use your browser to log into RT. Username is root, and password is password. Change your password.

Comments, questions, problems

Upgrades (old but likley still relevant)

3.6.1 is out in portage! Can anyone provide some advice on how to upgrade from 3.6.0 to 3.6.1 in gentoo?

Normally this should just be as easy as webapp-config -U -h rt.domain.foo rt 3.6.1. However, the problem here is that none of the ebuilds follow a common structure. eg, some of them install the RT html data into the htdocs, some install into the default hostroot/rt/share/html. It also looks like somewhere along the line someone's changed the default install prefix from hostroot/rt to hostroot/rt-version, so 3.6.1 will install to hostroot/rt-3.6.1 -- TomLanyon