Running HTML::Mason With nginx And FastCGI
This article is a step by step guide to install the HTML::Mason module to use with the ngingx web server and FastCGI. It has been tested in Debian (lenny), but it should be very similar with Ubuntu and other debian based distros.
Installing a minimal running server
First of all we will install a minimal server with nginx and FastCGI. I made basic scripts to make it run. Later we can customize those scripts.
Install nginx
Now we install nginx and get it working. It is assumed there is no other web server up in the host. Everything will be installed by default.
apt-get install nginx
Let's see if it does work telnetting to port 80.
/etc/init.d/nginx start
telnet locahost 80
Escape character is '^]'
GET /
<htm>
<head>
<title>Welcome to ngingx!<title>
...
Install FastCGI
apt-get install libcgi-fast-perl libio-all-perl
Install HTML::Mason
HTML::Mason is supossed to need apache2 to run, so it will download and install it. We will get rid of it later.
apt-get install libhtml-mason-perl
apt-get --purge remove apache2-mpm-worker apache2-utils
apt-get --purge autoremove
Hopefully, we now have HTML::Mason installed and no apache traces. Make sure nginx is still working checking it still answers on port 80.
Configure FastCGI
We need a FastCGI server running so it can execute HTML::Mason code. This script will download all the configuration and init files. We must run it as root. Please take a look at it before running it. It downlads and copies some files from github. It could be dangerous to your server.
wget http://github.com/frankiejol/mason-fcgi/raw/master/download.sh
bash ./download.sh
It is very important to change the server_name option in /etc/nginx/sites-available/mason to the real name of the server. Localhost won't work. Then modify the %SITES variable in /var/www/mason/mason_fcgi.pl.
Running Mason code
Finally let's create a simple Mason page.
mkdir /var/www/site1
echo '<% 2 + 2 %>' > /var/www/site1/index.html
Then let's start the service. A 4 should appear if you connected the site with your browser.
/etc/init.d/nginx restart
/etc/init.d/fcgi start
Customizing the server
Right now we have a nginx+FastCGI powered Mason server. All the configuration files and scripts can be found in my github repository.
nginx
nginx configuration is in /etc/nginx/sites-available/mason. The location can be modified to suite your need. Notice there are two rewrite lines because Mason can't handle directories properly. So when the request looks like a directory, an index.html postfix is added.
FastCGI
The FastCGI startup script is /var/www/mason/mason_fcgi.pl. A bunch of arguments can be supplied.
/var/www/mason/mason_fcgi.pl --help
mason_fcgi.pl [--help] [--pid=/var/run/fcgi/fcgi.pid] [--log=/var/log/nginx/fcgi/fcgi.log] [--debug] [--socket=/var/run/fcgi/mason_fcgi.sock] [--basedir=/var/www] [--workspace=/var/www/mason/workspace] [--error-uri=/errors/503.html] [--listen-queue=100] [--default-host=debian.localdomain]
There is a section to add the loading of Perl modules and global variables. This is the default code:
{
package HTML::Mason::Commands;
# use My::Own::Module;
# use Data::Dumper;
# anything you want available to components
use vars(qw($DBH %stash));
}
Running multiple FastCGI sites
The FastCGI daemon is run from /etc/init.d/fcgi. This script loads the configuration from /etc/default/fcgi. If you need more FastCGI servers for different sites. Just copy the init script to another name and call the config file the same. The init script will load a file in /etc/default with the same basename as itself.
