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 '^]'
<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.

bash ./

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/


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



The FastCGI startup script is /var/www/mason/ A bunch of arguments can be supplied.

/var/www/mason/ --help [--help] [--pid=/var/run/fcgi/] [--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.


Share this page:

0 Comment(s)