Catalyst

From DreamHost

Contents 1 Catalyst Web Framework 2 Installing on DreamHost 2.1 Disclaimer 2.2 Configure your site in the panel 2.3 Configure a custom CPAN user environment 2.4 Configure CPAN to use user library 2.5 Install and build lots 2.6 Sanity Check 3 Create an application 4 Running the application under FastCGI 5 Optional Download of local::lib and Task::Catalyst

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

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.

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

• From the shell, run cpan, answer no and type bye.
• edit the following lines in ~/.cpan/CPAN/MyConfig.pm
  • Be sure to replace USERNAME with your username

...
'make_install_arg' => q[SITEPREFIX=/home/USERNAME/local],
'makepl_arg' => q[INSTALLDIRS=site INSTALL_BASE=/home/USERNAME/local],
...
'urllist' => [q{http://cpan.pair.com/}],
...
'prerequisites_policy' => q[follow],

Install and build lots

• Log into your shell: Make sure you are in bash
• bash
• perl -MCPAN -e 'install Module::Build'
• wget http://www.shadowcatsystems.co.uk/static/cat-install
• perl cat-install ( you may need to run this a few times before it can get all the dependencies installed
• perl -MCPAN -e 'install Catalyst::Devel'
• cp ~/.cpan/build/Catalyst-Runtime-5.7007/script/catalyst.pl ~/local/bin ( Do this now, because after installing the upcoming list, cpan is probably going to purge it's build cache. Version number may be different for your build )
• run cpan and pass it this install list. Then pass it the same list just to be sure. Maybe even a third time if you're a skittish person. Four times is just silly.

install Template::Timer
install PadWalker
install Cache::FastMmap
install Devel::Caller
install Devel::LexAlias
install Catalyst::Plugin::ConfigLoader
install Catalyst::Plugin::Static::Simple
install Catalyst::Plugin::StackTrace
install Catalyst::Model::CDBI
install DBIx::Class::ResultSource
install Class::DBI::SQLite
install Catalyst::Model::DBIC::Schema
install Catalyst::Helper::Model::DBIC::Schema
install Catalyst::Helper::View::TT
install Catalyst::Helper::View::TTSite
install Catalyst::Plugin::Authentication
install Catalyst::Plugin::Authentication::Store::DBIC
install Catalyst::Plugin::Authentication::Credential::Password
install Catalyst::Plugin::Session
install Catalyst::Plugin::Session::Store::FastMmap 
install Catalyst::Plugin::Session::State::Cookie
install Catalyst::Plugin::Authorization::Roles
install Catalyst::Action::RenderView
install Catalyst::Controller::BindLex
install Catalyst::Plugin::I18N

• If everything looks good, say bye to cpan and get back to your shell

N.B. DreamHost's process killer will kill CPAN if it is taking up too much memory. I experienced this while installing a few modules such as DBIx::Class, when doing a make test. For these, try adding notest before the install command to skip the test. Alternatively, you can try 'nice'ing cpan to a lower priority. Try 'nice -n 19 cpan' and continue installing the modules.

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
cd
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 ~/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

• Test/script/test_cgi.pl
• Test/script/test_fastcgi.pl

#!/usr/bin/env perl
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
];

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 "<your ip here>"
[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.