Home | Wiki | OI 1.x Docs | OI 2.x Docs OI logo

SYNOPSIS

This section of the OpenInteract2 manual will show you how to compile Apache and mod_perl for a two-server proxy setup, along with other information for configuring Apache.

DESCRIPTION

First: Apache and mod_perl really aren't difficult to setup. As long as you have a standard C compiler (GCC!) and a little patience, the keys to the future are yours!

APACHE 1.x OVERVIEW

OpenInteract2 depends on a persistent Perl environment within a web server. Currently, the best alternative is mod_perl 1.x.

mod_perl is extremely powerful, but this power can come at a price. Embedding Perl into Apache uses more resources (particularly memory) than just using Apache alone. A number of developers have experimented with various ways of minimizing the memory footprint of mod_perl, and one of the easiest and best performing methods is to use a proxy server.

This is described in great detail in the mod_perl guide under the Choosing the Right Strategy heading. But we'll summarize here:

The benefits of this are:

Running OpenInteract2 in this environment is strongly recommended, and it comes with configuration files that make it easier to do the Right Thing.

BUILDING APACHE 1.x

First, you need to get the mod_proxy_add_forward module make available by Ask Bjoern Hansen. (See the resources at the end of the document.)

Once you've retrieved the file, copy it into the src/modules/extra directory of your Apache source code directory. An example of the 'activate-module' and 'enable-module' directives to put this module into your Apache is below in the as well as in the source code for mod_proxy_add_forward itself. Once you've retrieved the extra module and copied it to the right place, you can create apache and mod_perl with the following steps. Note that this assumes you have not installed apache from source before and that you're installing to the directory /usr/local/apache -- modify as needed.

  
  1.  $ tar -zxvf apache-1.3.23.tar.gz
  
  2.  $ tar -zxvf mod_perl-1.26.tar.gz
  
  3.  $ cd apache-1.3.23
  
  4.  $ ./configure --prefix=/usr/local/apache \ 
             --enable-module=rewrite --enable-module=proxy \
             --activate-module=src/modules/extra/mod_proxy_add_forward.c \
             --enable-module=proxy_add_forward
  
  5.  $ make
  
  6.  $ make install
  (proxy server binary is now installed as /usr/local/apache/bin/httpd)
  
  7.  $ cd ../mod_perl-1.26
  
  8.  $ perl Makefile.PL EVERYTHING=1
  
  # Configure mod_perl with ../apache_1.3.23/src ? [y]
  9.  $ y
  
  # Shall I build httpd in ../apache_1.3.23/src for you? [y]
  10. $ y
  
  11. $ make
  
  12. $ make test
  (note: if this fails due to an error with URI::URL, set the
  environment variable 'PERL_HTTP_URI_CLASS' to 'URI::URL', with
  something like:
  
  $ export PERL_HTTP_URI_CLASS=URI::URL
  
  13. $ make install
  (mod_perl Perl modules are now installed)
  
  14. $ cp ../apache-1.3.23/src/httpd /usr/local/apache/bin/httpd_modperl
  (mod_perl-enabled Apache is now installed)
  

This is a very simple method for creating both a lightweight proxy Apache binary and a heavyweight mod_perl-enabled Apache binary. See the mod_perl Guide for many, many more details about building mod_perl.

It is strongly recommended that you do not build mod_perl using DSOs and that you do not use pre-built versions such as those supplied by RedHat with its RPMs. However, using the DSO mechanism probably works fine for the front-end proxy server.

CONFIGURING APACHE 1.x

Use oi2_manage! Use OI2_MANAGE!

The oi2_manage script included with OpenInteract2 performs a number of tasks for you that make your life much easier. When you run the create_website command along with the appropriate parameters, oi2_manage will copy configuration files from the base installation to your website directory and customize them for your website.

For instance, two of the files that are copied to your website's conf/ directory are httpd_static.conf and httpd_modperl.conf. (See the httpd_static.conf and httpd_modperl.conf files from the sample/apache/ directory in the distribution. The items marked with '[% %]' TT syntax are replaced in the customization process.) You will still need to edit a few parameters in them -- oi2_manage is pretty smart, but it can't find out which IP address you want your website to listen to! -- but much of it is filled in for you.

Static Configuration

After you've run oi2_manage, you will need to modify a few parameters in the static Apache configuration file.

Proxy configuration is fairly simple. Every rule (starting with RewriteRule) is processed in order. Once a rule is met, no further rules are processed unless the satisfied rule specifies it.

The default proxy configuration assumes that the only static files you will want to serve directly from the proxy server are images. This action is specified by this line:

  RewriteRule ^/images - [L]

If you want to add other locations that will be entirely served by the lightweight server, just add them after this line. For example, if my website had a directory '/forms' where we kept PDF versions of forms for our customers to fill out, I could add:

  RewriteRule ^/forms - [L]

And every URL beginning with /forms will be answered by the front-end lightweight server. The [L] stands for "Local" and means that you want this server (the proxy server) to handle the request.

The only word of warning here is that as an administrator you might need to keep an eye on what the back-end server is using for URLs. For instance, say I entered this /forms configuration directive and later a developer on the back-end server tries to configure OpenInteract2 to perform a certain action when given the /forms URL. Unless the developer knows that the front-end server is answering all the /forms URLs, she will have a very frustrating time trying to figure out why her handler isn't responding.

mod_perl Configuration

After you've run oi2_manage, you will need to modify a few parameters in the mod_perl Apache configuration file.

You can skip the remainder of this section if you just want to get something up and running. The oi2_manage script takes care of all this for you. But if you're curious, read on.

Additional mod_perl Configuration

Four separate items need to be customized in the conf/httpd_modperl.conf file:

First, define the library paths for this website. Note that this is applied on a server-wide basis, so be careful of namespace clashes.

Example:

  <Perl>
    use lib qw( /home/httpd/mysite.com );
  </Perl>

Second, you need to bring in your startup.pl. (Information on what is done in the startup.pl is found in the OpenInteracts Developer's Guide.)

  PerlRequire /home/httpd/mysite.com/conf/startup.pl

TODO: Modify this to deal with being deployed under a separate directory.

Third and finally, we need to ensure that every request coming in goes through a single Apache content handler: Apache::OpenInteract2. To enable this, just do:

  <Location /> 
    SetHandler perl-script 
    PerlHandler Apache::OpenInteract2
  </Location>

We can just say "Apache::OpenInteract2" in the httpd.conf file because we have already included the library in our startup.pl.

Since OpenInteract2 allows you to deploy the application under a different URL context you can also use something like:

  <Location /OI2> 
    SetHandler perl-script 
    PerlHandler Apache::OpenInteract2
  </Location>

As long as you accompany it with a matching entry in the server configuration key 'context_info.deployed_under'.

GOTCHAS FOR APACHE 1.x

SEE ALSO

mod_proxy_add_forward

http://develooper.com/code/mpaf/mod_proxy_add_forward.c

mod_perl Guide http://perl.apache.org/guide/

General Apache documentation

http://www.apache.org/docs/

Apache: Listen directive

http://www.apache.org/docs/mod/core.html#listen

Apache: NameVirtualHost directive

http://www.apache.org/docs/mod/core.html#namevirtualhost

mod_rewrite manual

http://www.apache.org/docs/mod/mod_rewrite.html

Apache Virtual Host documentation

http://www.apache.org/docs/vhosts/index.html

COPYRIGHT

Copyright (c) 2002-2003 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>

Generated from the OpenInteract 1.99_03 source.


Home | Wiki | OI 1.x Docs | OI 2.x Docs
SourceForge Logo