Catalyst

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

Disclaimer
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 &gt; Manage Domains &gt; Add New Domain
 * Domain To Host: catalyst.yourdomain.com
 * FastCGI Support: YES
 * FTP User: Create New User
 * How do you like the www?: Select Remove WWW'
 * Create your domain
 * Users &gt; Manage Users &gt; 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. 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
 * ~/.bash_profile
 * ~/.bashrc
 * 1) define custom perl libraries

Configure CPAN to use user library

 * From the shell, run cpan, answer no and type bye.
 * Install local::lib - http://search.cpan.org/~mstrout/local-lib-1.006000/lib/local/lib.pm#The_bootstrapping_technique
 * Install cpanm - http://search.cpan.org/~miyagawa/App-cpanminus-1.0003/lib/App/cpanminus.pm

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. cd rm -R -f .cpan local If you still can't get things working, there are lots of places to seek help
 * 1) If you have to start over, you can say THIS from the shell and start over

Create an application
Do this cd ~/catalyst.mysite.com ( or whatever your domain name is ) catalyst.pl Test chmod a+rx Test/script/test_cgi.pl Test/script/test_fastcgi.pl 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 use lib qw[ /home/myusername/local/lib/perl5 /home/myusername/local/share/perl/5.8.8 /home/myusername/local/lib/perl/5.8.8 /home/myusername/local/lib ];
 * Test/script/test_cgi.pl
 * Test/script/test_fastcgi.pl
 * 1) !/usr/bin/env perl

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:

http://catalyst.mysite.com/Test/script/test_cgi.pl (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/catalyst.mysite.com/Test" [debug] Loaded Config "/home/myusername/catalyst.mysite.com/Test/Test.conf" [debug] Loaded components: .-+--. | Class                                                          | Type     | +-+--+ | Test::Controller::Root                                         | instance | '-+--' ... (several similar lines removed ) ... .-+--. | Parameter                          | Value                                | +-+--+ | action                             | default                              | '-+--' [debug] "GET" request for "/Test/script/test_cgi.pl" from " " [debug] Arguments are "/Test/script/test_cgi.pl" [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/domainname.com/myapp.

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 myapp_fastcgi.pl in the /home/myusername/domainname.com/myapp/script directory and rename it to dispatch.fcgi. Then, create a .htaccess in the /home/myusername/domainname.com 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 ~/domainname.com/myapp/script/dispatch.fcgi

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 PERL_MM_OPT="INSTALL_BASE=/home/YOUR_USERNAME/perl5" 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.

GZIP / FASTCGI
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 irc.perl.org. There are more details about the problem at http://wiki.catalystframework.org/wiki/deployment/apache_fastcgi''

Application Times Out
I followed these instructions, and was able to successfully test with both xxx_test.pl and xxx_cgi.pl, 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:

use lib qw | /home/username/local/lib/perl5/x86_64-linux-gnu-thread-multi /home/username/local/lib/perl5 /home/username/local/share/perl/5.8.8 /home/username/local/lib/perl/5.8.8 /home/username/local/lib/ | ;
 * 1) !/usr/bin/env perl
 * 1) These values prepended to @INC are the result of earlier steps creating your local libraries
 * 2) 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.