OpenInteract2::Manual::AdminApache - Compiling and configuration Apache/mod_perl 1.x
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.
Apache and mod_perl really aren't difficult to setup. As long as you have a standard C compiler (GCC!) and a little patience it's really a piece of cake.
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:
Setup a plain Apache server with mod_proxy and mod_rewrite to listen to port 80 for your website. (We describe the build process below.)
Tell this server to deal with static file requests (images, movies, PDFs, etc.)
Proxy all other requests back to a heavier mod_perl server.
Receive the information back from the mod_perl server and send to the client.
The benefits of this are:
Resource-hogging mod_perl processes do not serve static files -- if they did, you'd need more of the processes.
Since OI2 can run under a URL context you can segment your site to different application servers. For instance, you can say that everything under '/oi' goes back to your OI2 application server running under mod_perl and everything under '/jsp' goes to a Tomcat web container with your Java Server Pages. But to the user it's all under one site -- nifty.
The front-end proxy is able to feed data back to the client at whatever rate it needs without taking up many resources the entire time. For instance, users reaching your website with modems can tie up a web server process for much longer than users who are on some sort of broadband network. If the process is small it's not such a big deal.
Since they are separate, you can make changes to the (heavy) back-end and mask them by the (light) front-end. This is a great help when things are going wrong with the back-end and you don't want users to see nasty error pages.
Also since they are separate, you can very easily move the back-end process to an entirely separate machine (or machines, using some sort of DNS or load-balancing manipulation) if the need arises.
Running OpenInteract2 in this environment is strongly recommended, and it comes with configuration files that make it easier to do the Right Thing.
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.
/usr/local/apache
1. $ tar -zxvf apache-1.3.33.tar.gz
2. $ tar -zxvf mod_perl-1.29.tar.gz 3. $ cd apache-1.3.33 4. $ ./configure --prefix=/usr/local/apache \ --enable-module=rewrite --enable-module=proxy \ 5. $ make 6. $ make install (proxy server binary is now installed as /usr/local/apache/bin/httpd) 7. $ cd ../mod_perl-1.29 8. $ perl Makefile.PL EVERYTHING=1 # Configure mod_perl with ../apache_1.3.33/src ? [y] 9. $ y # Shall I build httpd in ../apache_1.3.33/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.33/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.
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. This includes a set of files to get Apache running quite easily.
oi2_manage
create_website
Each Apache file defines a VirtualHost and is meant to be Included into a main server configuration. For instance, one of the files we generate is conf/httpd_modperl.conf. Assuming you created your website in /home/httpd/mysite.com you'd add the following to your main mod_perl server configuration:
VirtualHost
Included
conf/httpd_modperl.conf
/home/httpd/mysite.com
Include /home/httpd/mysite.com/conf/httpd_modperl.conf
and Apache will bring in the file at runtime. Of course, you can always copy-and-paste if that floats your boat, but you'll probably find that using Include makes your life easier.
Include
There are four Apache 1.x configuration files created for you in the conf/ website directory:
conf/
httpd_cgi_solo.conf - If you want to run OI2 as a CGI script you can use this. (This configuration is NOT RECOMMENDED because of performance but you might find it useful.)
httpd_cgi_solo.conf
httpd_modperl_solo.conf - If you want to run OI2 in a mod_perl-enabled server without a front-end proxy, use this.
httpd_modperl_solo.conf
httpd_static.conf - If you want to run OI2 with a proxy configuration, this is the VirtualHost to use for the front-end. It proxies all requests except for static files back to a mod_perl server.
httpd_static.conf
httpd_modperl.conf - If you want to run OI2 with a proxy configuration, this is the VirtualHost to use for the back-end inside a mod_perl server.
httpd_modperl.conf
All files are customized to your setup so you won't need to change any directory or file information. 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!
After you've run oi2_manage, you will need to modify a few parameters in the httpd_static.conf if you're using the front-end proxy setup:
IP address: Do a search-replace for '127.0.0.1' with the IP address you want the website to listen to. Note that if you're using named virtual hosts you should remove the Listen directive. You will also need to specify the NameVirtualHost directive in your main Apache configuration file.
Listen
NameVirtualHost
ServerAdmin: Change the value for the 'ServerAdmin' key
ServerName: Change the value for the 'ServerName' key
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.
RewriteRule
The default proxy configuration assumes that the only static files you will want to serve directly from the proxy server are images. That 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.
/forms
[L]
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'll have a very frustrating time trying to figure out why her handler isn't responding.
After you've run oi2_manage, you will need to modify a few parameters in the mod_perl Apache configuration file -- this holds whether you're modifying httpd_modperl_solo.conf or httpd_modperl.conf:
IP address: Do a search-replace for '127.0.0.1' with the IP address you want the website to listen to.
Port: (optional) Do a search-replace for the default value of '8080' with whatever port you want to run the mod_perl server on.
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.
The files copied by oi2_manage use the following items in conf/httpd_modperl.conf:
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, we need to bring in the startup.pl -- this includes a few modules for us and initializes the OpenInteract2::Context object once at server startup.
startup.pl
PerlRequire /home/httpd/mysite.com/conf/startup.pl
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'.
DO NOT restart the Apache/mod_perl process using the HUP signal. Your modules will not get reloaded properly, but everything will appear to work. Very tricky.
HUP
If images don't show when accessing the Virtual Host you're setting up, it may be worth looking at the Apache default configuration. Some default configurations specify a global alias for the "/images" location, and if this is the case, you can easily override it by adding something like this to your VirtualHost config:
Alias /images /path/to/your/installation/html/images
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 (c) 2002-2005 Chris Winters. All rights reserved.
Chris Winters <chris@cwinters.com>
To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenInteract2::URL
CPAN shell
perl -MCPAN -e shell install OpenInteract2::URL
For more information on module installation, please visit the detailed CPAN module installation guide.