343336 - Document how to set up Apache for mod_perl

Status: RESOLVED FIXED

(Bugzilla :: Documentation, enhancement)

Description

[Max Kanat-Alexander]

We need to explain to end users how to set up Bugzilla to run under mod_perl.

I'll supply the information for this, but somebody else will have to convert it into the XML.

Comment 1

[Max Kanat-Alexander]

Essentially, they need to:

1) Install mod_perl (http://perl.apache.org/) at least 1.999022 (AKA 2.0.0-RC5)

2) Put this in their Apache configuration:

PerlSwitches -I/var/www/html/mod_perl -w -T
<Directory /var/www/html/mod_perl>
    AddHandler perl-script .cgi
    PerlResponseHandler ModPerl::Registry
    PerlOptions +ParseHeaders
    Options +Indexes +ExecCGI
    DirectoryIndex index.cgi
    AllowOverride Limit
</Directory>

  Replacing /var/www/htlm/mod_perl with the name of their Bugzilla directory.

  That should be used instead of the normal <Directory> block for Bugzilla.

Comment 2

[Marcus Pallinger]

Out of curiosity, could this stuff go in the appropriate .htaccess files?

Comment 3

[Max Kanat-Alexander]

(In reply to comment #2)
> Out of curiosity, could this stuff go in the appropriate .htaccess files?

  The Perl stuff could not--that has to happen when Apache starts. At least, PerlSwitches has to. I'm not sure about the other ones.

Comment 4

[Max Kanat-Alexander]

We should also mention that KeepAlive is very bad for mod_perl servers, and should definitely be OFF in Apache if you're going to use mod_perl. It's explained somewhere deep in the mod_perl docs, but we should just mention it directly.

The reason is this:

With KeepAlive enabled, the server waits around 15 seconds for you to send another response. This means that further responses for other clients have to spawn more and more httpd children. Lots of httpd children is extra-bad with mod_perl, because each child can take up so much RAM. The whole point of mod_perl is to make one httpd child able to service hundreds and hundreds of requests very quickly.

Comment 5

[Max Kanat-Alexander]

As soon as bug 345376 is checked in, the configuration will also require this line, right below PerlSwitches (outside of the Directory block):

PerlRequire /var/www/html/bugzilla/mod_perl.pl

Where /var/www/html/bugzilla is the name of the directory (what I was previously calling /var/www/html/mod_perl).

Comment 6

[Max Kanat-Alexander]

Okay, configuration has changed. Now, you ONLY need these two lines, and you don't need ANY <Directory> block at all:

PerlSwitches -I/var/www/html/mod_perl -w -T
PerlConfigRequire /var/www/html/mod_perl/mod_perl.pl

The two lines must be in that order, and they must be before any other mod_perl configuration.


There are some other things to know:

* 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.

* 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 *restart* the server (as in make sure it stops and starts again). You *can* change localconfig and the params file manually, if you want, because those are re-read every time you load a page.

* Make sure KeepAlive is off, as I specified above.

* 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 *won't* work.)

* 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.

* You may only have one Bugzilla instance running under mod_perl on your server. (At least, I think. I haven't tested it, but it's probably true.)

Comment 7

[Colin Ogilvie [:cso]]

Attachment: Patch v1

Patch

Comment 8

[Colin Ogilvie [:cso]]

Comment on attachment 240669 [details] [diff] [review]
Patch v1

>Index: docs/xml/installation.xml
>-          </para>
>+          </para>s

Will remove on checkin if Max agrees with the docs.

Comment 9

[Max Kanat-Alexander]

Comment on attachment 240669 [details] [diff] [review]
Patch v1

>@@ -638,7 +654,7 @@
>-      with Bugzilla. Currently <xref linkend="mysql"/> and
>+        with Bugzilla. Currently <xref linkend="mysql"/> ands

  That should also go away.

>+            <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>
> [snip]

  This step applies to both mod_perl and mod_cgi. For mod_perl, you have to fix the permissions before you restart the webserver.

>+                <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>
>+                blocks within the <filename>httpd.conf</filename>

  It's actually not just blocks, but directives. Although I don't know how clear that would be to end-users?

>+                <programlisting>
>+    PerlSwitches -I/var/www/html/mod_perl -w -T
>+    PerlConfigRequire /var/www/html/mod_perl/mod_perl.pl
>+                </programlisting>
>+            </step>

  You'll probably want to change that to /var/www/html/bugzilla, just like above.

>+                    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 *restart* the

  You could actually make the ** stuff italic, right?

  Everything else looks fine, so r+ with those changes.

Comment 10

[Frédéric Buclin]

This patch only affects documentation. Colin, you can check it in before the 2.23.3 release.

Comment 11

[Colin Ogilvie [:cso]]

Checking in docs/xml/installation.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/installation.xml,v  <--  installation.xml
new revision: 1.130; previous revision: 1.129
done