Bug 343336: Document how to set up Apache for mod_perl

docs/en/xml/installation.xml

 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.129 2008/04/04 06:47:59 mozilla%colinogilvie.co.uk Exp $ -->
+<!-- $Id: installation.xml,v 1.130 2008/04/04 06:48:00 mozilla%colinogilvie.co.uk Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -287,7 +287,7 @@
 
         <listitem>
           <para>
-            CGI (&min-cgi-ver;)
+            CGI &min-cgi-ver; or CGI &min-mp-cgi-ver; if using mod_perl
           </para>
         </listitem>
 
@@ -567,7 +567,23 @@
       </para>
 
     </section>  
+    <section id="using-mod_perl-with-bugzilla">
+      <title>Installing Bugzilla on mod_perl</title>
+      <para>It is now possible to run the Bugzilla software under <literal>mod_perl</literal> on
+      Apache. <literal>mod_perl</literal> has some additional requirements to that of running
+      Bugzilla under <literal>mod_cgi</literal> (the standard and previous way).</para>
       
+      <para>Bugzilla requires <literal>mod_perl</literal> to be installed, which can be
+      obtained from <ulink url="http://perl.apache.org"/> - Bugzilla requires
+      version &min-mp-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed.</para>
+      
+      <para>Bugzilla also requires a more up-to-date version of the CGI
+      perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver;
+      </para>
+      
+      <para>Finally, Bugzilla also requires <literal>Apache::DBI</literal>
+      (&min-mp-apache-dbi-ver;) to be installed as well.</para>
+    </section>
   </section>
   
   
@@ -874,11 +890,18 @@
       </para>
 
       <section id="http-apache">
-        <title>Apache <productname>httpd</productname></title>
+        <title>Bugzilla using Apache</title>
+        <para>You have two options for running Bugzilla under Apache - 
+          <link linkend="http-apache-mod_cgi">mod_cgi</link> (the default) and
+          <link linkend="http-apache-mod_perl">mod_perl</link> (new in Bugzilla
+          2.23)
+        </para>
+        <section id="http-apache-mod_cgi">
+            <title>Apache <productname>httpd</productname> with mod_cgi</title>
     
             <para>
-          To configure your Apache web server to work with Bugzilla,
-          do the following:
+            To configure your Apache web server to work with Bugzilla while using
+            mod_cgi, do the following:
             </para>
             
             <procedure>
@@ -902,12 +925,12 @@
                 </para>
     
                 <programlisting>
-&lt;Directory /var/www/html/bugzilla&gt;
+    &lt;Directory /var/www/html/bugzilla&gt;
     AddHandler cgi-script .cgi
     Options +Indexes +ExecCGI
     DirectoryIndex index.cgi
     AllowOverride Limit
-&lt;/Directory&gt;
+    &lt;/Directory&gt;
                 </programlisting>
     
                 <para>
@@ -967,6 +990,107 @@
             </step>
             </procedure>
         </section>
+        <section id="http-apache-mod_perl">
+            <title>Apache <productname>httpd</productname> with mod_perl</title>
+            
+            <para>Some configuration is required to make Bugzilla work with Apache
+            and mod_perl</para>
+            
+            <procedure>
+            <step>
+                <para>
+                Load <filename>httpd.conf</filename> in your editor.
+                In Fedora and Red Hat Linux, this file is found in
+                <filename class="directory">/etc/httpd/conf</filename>.
+                </para>
+            </step>
+            
+            <step>
+                <para>Add the following information to your httpd.conf file, substituting
+                where appropriate with your own local paths.</para>
+                
+                <note>
+                <para>This should be used instead of the &lt;Directory&gt; block
+                shown above. This should also be above any other <literal>mod_perl</literal>
+                directives within the <filename>httpd.conf</filename> and must be specified
+                in the order as below.</para>
+                </note>
+                <warning>
+                <para>You should also ensure that you have disabled <literal>KeepAlive</literal>
+                support in your Apache install when utilizing Bugzilla under mod_perl</para>
+                </warning> 
+                
+                <programlisting>
+    PerlSwitches -I/var/www/html/bugzilla -w -T
+    PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
+                </programlisting>
+            </step>
+			
+			<step>
+				<para>
+					<filename>checksetup.pl</filename> can set tighter permissions
+					on Bugzilla's files and directories if it knows what group the
+					webserver runs as. Find the <computeroutput>Group</computeroutput>
+					line in <filename>httpd.conf</filename>, place the value found
+					there in the <replaceable>$webservergroup</replaceable> variable
+					in <filename>localconfig</filename>, then rerun
+					<filename>checksetup.pl</filename>.
+				</para>
+            </step>
+            </procedure>
+            
+            <para>On restarting Apache, Bugzilla should now be running within the
+            mod_perl environment. Please ensure you have run checksetup.pl to set
+		    permissions before you restart Apache.</para>
+        
+            <note>
+            <para>Please bear the following points in mind when looking at using 
+                Bugzilla under mod_perl: 
+            <itemizedlist>
+                <listitem>
+                <para>
+                    mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be
+                    lookng at 30MB per httpd child, easily. Basically, you just need a lot of RAM.
+                    The more RAM you can get, the better. mod_perl is basically trading RAM for
+                    speed. At least 2GB total system RAM is recommended for running Bugzilla under
+                    mod_perl.
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    Under mod_perl, you have to restart Apache if you make any manual change to
+                    any Bugzilla file. You can't just reload--you have to actually 
+					<emphasis>restart</emphasis> the server (as in make sure it stops and starts 
+					again). You <emphasis>can</emphasis> change localconfig and the params file 
+					manually, if you want, because those are re-read every time you load a page.
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    You must run in Apache's Prefork MPM (this is the default). The Worker MPM
+                    may not work--we haven't tested Bugzilla's mod_perl support under threads.
+					(And, in fact, we're fairly sure it <emphasis>won't</emphasis> work.)
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    Bugzilla generally expects to be the only mod_perl application running on
+                    your entire server. It may or may not work if there are other applications also
+                    running under mod_perl. It does try its best to play nice with other mod_perl
+                    applications, but it still may have conflicts.
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    It is recommended that you have one Bugzilla instance running under mod_perl
+                    on your server. Bugzilla has not been tested with more than one instance running.
+                </para>
+                </listitem>
+            </itemizedlist>
+            </para>
+            </note>
+        </section>
+      </section>
       
       <section id="http-iis">
         <title>Microsoft <productname>Internet Information Services</productname></title>