Catalyst and mod_perl
Updated by Linode Written by Linode
DeprecatedThis guide has been deprecated and is no longer being maintained.
The Catalyst web framework is a contemporary Perl-based MVC, or Model View Controller. Like similar projects such as Django, Ruby On Rails, and Seaside, Catalyst promotes efficient and rapid development, clear application logic, and web centric development paradigms. If you are used to developing applications with Perl and would like to develop modern web applications, you may consider using the Catalyst framework.
In this document, we outline deploying applications developed with Catalyst using the Apache web server and the
mod_perl method of running Perl applications embedded in the web server process. Before installing Catalyst, we assume that you have followed our getting started guide. If you are new to Linux server administration, you may be interested in our introduction to Linux concepts guide, beginner’s guide and administration basics guide.
Although the Catalyst framework is packaged and included in the repositories of a number of major Linux-based operating system distributions, this document provides a procedure for installing the Catalyst framework from CPAN repositories. This will ensure that your application will have access to the most recently developed features.
Preparing the System for Catalyst
If you have not yet installed a development tool chain including Perl and its dependencies, issue the following commands on Debian and Ubuntu systems to install this software and make sure that your system’s package database and installed software are up to date:
apt-get update apt-get upgrade apt-get install perl build-essential curl
Similarly on CentOS and Fedora systems, use the following commands to update the system and install the required software:
yum update yum groupinstall "Development Tools" yum install perl perl-devel curl gcc wget
On Arch Linux systems issue the following commands to download the latest package database and install the Perl dependencies:
pacman -Sy pacman -S perl base-devel curl
This document will install all of the required modules for Catalyst using the CPAN Minus interface for CPAN. Install CPAN Minus by issuing the following sequence of commands:
cd /opt/ curl https://github.com/miyagawa/cpanminus/raw/master/cpanm > cpanm chmod +x cpanm ln -s /opt/cpanm /usr/bin/
Issue the following command to install the required Catalyst dependencies from the CPAN. Do not be alarmed if this process takes a few moments:
cpanm --sudo --skip-installed Catalyst::Runtime Catalyst::Devel Catalyst::Engine::Apache
Installing Additional Dependencies
Your application may require additional dependencies and Perl modules. You will want to return to the CPAN Minus interface to install these dependencies before continuing with your deployment. Install additional modules by issuing commands in the following form:
cpanm --sudo --skip-installed [Module::Name]
Setting up the Apache Server with mod_perl
Once the required Catalyst and database dependencies are installed, we will continue to install the Apache HTTP server and its
mod_perl module. For more information regarding general purpose configuration, consider our more in-depth documentation for installing Apache and configuring the HTTP server. If you have not already installed these packages, issue the following command:
apt-get install apache2 libapache2-mod-perl2 apache2-mpm-prefork
In Catalyst deployments, you will need to restart the Apache web server before beginning, and then again in order to deploy new code. To restart the web server, issue the following command:
Deploying Catalyst Applications
For the purposes of this document we will assume that you have configured virtual hosting for the domain
example.com in the manner described in the installing Apache document. Please note that you can only deploy one Catalyst application in a given instance of Apache.
Configuring Apache and mod_perl
Within your Apache virtual host configuration, set the following directives.
- Apache Virtual Host Configuration
1 2 3 4 5 6 7 8 9 10
PerlSwitches -I/srv/www/example.com/application/lib/ <Perl> use lib qw( /srv/www/example.com/application/lib/ ); </Perl> PerlModule application <Location /> SetHandler modperl PerlResponseHandler application </Location>
Alter this example to include the path to your Catalyst application’s
lib/ directory. The
<Location> specified above ensures that all responses that begin with a slash will be handled by
modperl, and thus the Catalyst application. The
<Perl> directive block provides the Perl process embedded in the web server process information regarding the path of your Catalyst application. The
PerlModule directive forces Apache to load your application in memory when it starts, which allows for significantly faster execution times.
Serve Static Content Directly From Apache
It may be more effective to serve some resources directly from Apache without using the
modperl handler. Include the following or equivalent lines in your virtual hosting configuration:
- Apache Virtual Host Configuration
1 2 3 4
DocumentRoot /srv/www/example.com/public_html <Location /static> SetHandler default-handler </Location>
With these lines, requests for the resources
http://example.com/static/bkgrnd.jpg will be served from the resources
/srv/www/example.com/public_html/static/bkgrnd.jpg respectively. You can add exemptions for multiple locations within your virtual host by using the
SetHandler directive within location specific configuration sections. Ensure that the
<Location> directive is inserted after the
Apache Virtual Hosting Configuration
The following example represents a complete and fully functional virtual hosting configuration that combines elements from the previous three examples:
- Apache Virtual Host Configuration
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
<VirtualHost *:80> ServerAdmin email@example.com ServerName example.com ServerAlias www.example.com ErrorLog /srv/www/example.com/logs/error.log CustomLog /srv/www/example.com/logs/access.log combined DocumentRoot /srv/www/example.com/public_html/ PerlSwitches -I/srv/www/example.com/application/lib/ <Perl> use lib qw( /srv/www/example.com/application/lib/ ); </Perl> PerlModule application <Location /> SetHandler modperl PerlResponseHandler application </Location> <Location /static> SetHandler default-handler </Location> <Location /images> SetHandler default-handler </Location> <Location /media> SetHandler default-handler </Location> </VirtualHost>
In this example, all requests are handled by the Catalyst application except for requests for resources located beneath
/media. Requests for resources in these locations are served from the file system located beneath the
DocumentRoot, which is
/srv/www/example.com/public_html/ in this example.
Congratulations, you have now successfully configured a system for deploying Catalyst powered web applications!
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
Join our Community
This guide is published under a CC BY-ND 4.0 license.