From DreamHost
Jump to: navigation, search
This article or section may require a cleanup.
We are hoping to create articles that meet certain standards. Please discuss this issue on the talk page. Editing help is available.
Catalyst logo3.png

Catalyst Web Framework

Catalyst is an MVC web development framework. More details can be found on Wikipedia or at the official website.

Installing on DreamHost

The instructions provided in this article or section are considered advanced.

You are expected to be knowledgeable in the UNIX shell.
Support for these instructions is not available from DreamHost tech support.
Server changes performed by DreamHost may break your modifications. You, as the user, are responsible for troubleshooting and resolving issues with your customizations.

The instructions provided in this article or section require shell access unless otherwise stated.

You can use the PuTTY client on Windows, or SSH on UNIX and UNIX-like systems such as Linux or Mac OS X.
Your account must be configured for shell access in the Control Panel.
More information may be available on the article's talk page.


This installation was performed on the caprisun server on 2007-06-04. Other servers may yield different results.

Update: The steps were verified and updated using the shadow server as a test on 2009-06-01.

Update: Verified on 2010-3-08 on steelers. Troubleshooting section added by brainbuz.

Update: 2010-05-09 - Dumped the old convoluted install steps in favour of a simpler local::lib/cpanm/Catalyst::Runtime method - added by Mrdini

Configure your site in the panel

You're going to need some space to work, and a shell account. You may wish to create a subdomain and account specifically for learning to use Catalyst on DreamHost.

  • Log into the control panel
  • Domains > Manage Domains > Add Hosting to a Domain / Sub-Domain button
    • Domain To Host:
    • FastCGI Support: YES
    • FTP User: Create New User
    • How do you like the www?:' Select Remove WWW
    • Create your domain
  • Users > Manage Users > username
    • User Account Type: Shell Account
    • Set your password: MakeItAG0odP4ssw0RD!\ ITSyourSHELL!

Configure a custom CPAN user environment

You're going to be creating your own CPAN library for your user account. You need to alter your shell environment to accommodate the custom lib directories. Each Perl application you write that uses these libraries will need 'use lib' declarations.

Log into your shell account and add the following lines to both of these files. Then log out of your shell, and log back in to ensure the changes have taken effect.

  • ~/.bash_profile
  • ~/.bashrc
# define custom perl libraries
perlversion=`perl -v | grep 'built for' | awk '{print $4}' | sed -e 's/v//;'`
export PATH=$HOME/local/bin:$HOME/local/script:$PATH 
export PERL5LIB=$HOME/local/lib/perl5
export PERL5LIB=$PERL5LIB:$HOME/local/share/perl/$perlversion
export PERL5LIB=$PERL5LIB:$HOME/local/lib/perl/$perlversion
export PERL5LIB=$PERL5LIB:$HOME/local/lib

Configure CPAN to use user library

Install and build lots

  • Log into your shell: Make sure you are in bash
  • bash
  • perl -MCPAN -e 'install Module::Build'
    • This can sometimes cause your processes to be killed. I prefixed the command with "/usr/bin/nice -n 10" which allowed the perl build to continue.
  • cpanm Catalyst::Runtime
    • I ran into problems with installing HTTP::Headers which I solved by installing Encode
  • cpanm Catalyst::Devel
    • You may also need to install HTML::Entities

Sanity Check

At this point you should have a functioning installation of Catalyst. To be sure, try typing this at the shell:

perl -MCatalyst -e 'print "There is no *I* in team, but there is an *I* in pie"x100'

If your server is a fan of Shaun of the Dead then everything's all good. If not, something is screwed up. Or maybe you screwed up. Or both.

# If you have to start over, you can say THIS from the shell and start over
rm -R -f .cpan local

If you still can't get things working, there are lots of places to seek help

Create an application

Do this

cd ~/ ( or whatever your domain name is ) Test
chmod a+rx Test/script/ Test/script/

IMPORTANT!! This needs to be at the top of your app executable. For the purposes of your test app, place it at the top of the following files AFTER the shebang line

  • Test/script/
  • Test/script/
#!/usr/bin/env perl
use lib qw[

Don't forget to replace "myusername" with your actual username. Also, note that at the time of this writing, 5.8.8 is the deployed version of Perl on DreamHost but that is subject to change. Please verify that the directories you are including in the "use lib" statement actually exist.

At this point, you can test your setup by accessing the URL: (adjust domain portions accordingly)

If you get an "Internal Server Error" something is not configured correctly. Check your error log for clues and verify that you have completed all the steps above.

If you see a simple message "Page Not Found" you have Catalyst setup properly! This may seem like an error but it is the expected behavior with a default application that does not have any pages defined. If you tail your error log you should see lines like this:

[debug] Loaded dispatcher "Catalyst::Dispatcher"
[debug] Loaded engine "Catalyst::Engine::CGI"
[debug] Found home "/home/myusername/"
[debug] Loaded Config "/home/myusername/"
[debug] Loaded components:
| Class                                                           | Type     |
| Test::Controller::Root                                          | instance |
... (several similar lines removed ) ...
| Parameter                           | Value                                |
| action                              | default                              |
[debug] "GET" request for "/Test/script/" from "<your ip here>"
[debug] Arguments are "/Test/script/"
[info] Request took 0.006023s (166.030/s)
| Action                                                     | Time      |
| /default                                                   | 0.000223s |
| /end                                                       | 0.000419s |

You now have a working CGI configuration and are ready to proceed to the FastCGI instructions.

Running the application under FastCGI

These instructions are adapted from the Fastcgi set up entry. First, set up Catalyst as described above. For this example, Catalyst is setup in /home/myusername/

VERY IMPORTANT: DreamHost's has a very aggressive process killer that tends to kill the FastCGI server if it's idle for a while. However, if the server is named 'dispatch.fcgi', it does not seem to kill it. So be sure to rename the server script dispatch.fcgi!

To do this, find in the /home/myusername/ directory and rename it to dispatch.fcgi. Then, create a .htaccess in the /home/myusername/ directory. Add the following directives in the .htaccess file:

 Options +ExecCGI
 AddHandler fastcgi-script .fcgi
 RewriteEngine On
 RewriteRule ^(myapp/script/dispatch\.fcgi/.*)$ - [L]
 RewriteRule ^(.*)$ myapp/script/dispatch.fcgi/$1 [PT,L]

Make sure to make the FastCGI server executable:

 chmod +x dispatch.fcgi

Now, make your changes to your Catalyst application. To have those changes take effect, use the command:

 touch ~/

Optional Download of local::lib and Task::Catalyst

An archive has been created, available for downloaded, containing the following software:

  • local::lib 1.4.7
  • Task::Catalyst, as installed from CPAN on 2009-October-08.

The archive is located here. Available is both an archive (.tar.gz) and an uncompressed directory tree.

The local::lib directives (place them in .bashrc perhaps?):

export MODULEBUILDRC="/home/YOUR_USERNAME/perl5/.modulebuildrc"
export PERL5LIB="/home/YOUR_USERNAME/perl5/lib/perl5:/home/YOUR_USERNAME/perl5/lib/perl5/x86_64-linux-gnu-thread-multi:$PERL5LIB"
export PATH="/home/YOUR_USERNAME/perl5/bin:$PATH"

Remember to replace YOUR_USERNAME with .. your username. As always, this is entirely unsupported and it Works For Me. Your mileage may vary.



If your data is being truncated add to your .htaccess the following,

RewriteRule . - [E=no-gzip:1]

credit for this find goes to hobbs from #catalyst on There are more details about the problem at

Application Times Out

I followed these instructions, and was able to successfully test with both and, but everytime I tried to browse the site served from fcgi the request would time out (returning 500 to the browser) and die with a message in the http log for the site: FastCGI: incomplete headers (0 bytes) received from server. The fcgi environment wasn't picking up the local perl @INC. What worked for me was to type perl -V and paste the values into a use lib directive at the top of the dispatch.fcgi script, my code looks like:

#!/usr/bin/env perl

use lib qw |
| ;

# These values prepended to @INC are the result of earlier steps creating your local libraries 
# before you spent hours at the cpan prompt. 

If I had only gone back and looked at the create the test app part of the instructions again I would have saved a lot of frustration.