3 Catalyst::Manual::Installation - Catalyst Installation
7 How to install Catalyst.
11 One of the frequent problems reported by new users of Catalyst is that
12 it can be extremely time-consuming and difficult to install.
14 One of the great strengths of Perl as a programming language is its use
15 of CPAN, the Comprehensive Perl Archive Network, an enormous global
16 repository containing over 10,000 free modules. For almost any basic
17 task--and a very large number of non-basic ones--there is a module on
18 CPAN that will help you. Catalyst has taken advantage of this, and uses
19 a very large number of CPAN modules, rather than reinventing the wheel
20 over and over again. On the one hand, Catalyst gains power and
21 flexibility through this re-use of existing code. On the other hand,
22 Catalyst's reliance on CPAN can complicate initial installations,
23 especially in shared-hosting environments where you, the user, do not
24 have easy control over what versions of other modules are installed.
26 It is worth stressing that the difficulties found in installing Catalyst
27 are caused not by anything intrinsic to Catalyst itself, but rather by
28 the interrelated dependencies of a large number of required modules.
30 Fortunately, there are a growing number of methods that can dramatically
31 ease this undertaking. Note that for many of these, you will probably
32 need to install additional Catalyst-related modules (especially plugins)
33 to do the things you want. As of version 5.70, Catalyst has split into
34 two packages, L<Catalyst::Runtime>, which includes the core elements
35 necessary to deploy a Catalyst application, and L<Catalyst::Devel>,
36 which includes the Helpers and other things necessary or useful for
37 developing Catalyst applications. In a purely deployment environment
38 you can omit L<Catalyst::Devel>.
44 Matt Trout's C<cat-install> script
46 Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
47 C<cat-install> can be a quick and painless way to get Catalyst up and
48 running on your system. Just download the script from the link above
49 and type C<perl cat-install>. This script automates the process of
50 installing Catalyst itself and its dependencies, with bits of overriding
51 so that the process does not require user interaction. C<cat-install>
52 installs Catalyst and its dependencies using the L<CPAN> module, so that
53 modules are installed the same way you would probably install them
54 normally--it just makes it easier. This is a recommended solution for
59 Chris Laco's CatInABox
61 CatInABox is a complete version of Catalyst that is installed locally on
62 your system, so that you don't need to go through the effort of doing a
63 full install. Simply download the tarball from
64 L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
65 on your machine. Depending on your OS platform, either run C<start.bat>
66 or C<start.sh> to set your bin/PERLLIB paths. This tarball contains
67 everything needed to try out Catalyst including Catalyst itself,
68 Template Toolkit, several Authentication modules, StackTrace, and a few
71 A special Win32 version is available upon request that contains many
72 more plugins and pre-compiled modules, including DBIx::Class, DBI,
73 SQLite, and Session support. If you are interested in this version,
74 please send e-mail to C<claco@chrislaco.com>.
78 Pre-Built VMWare Images
80 Under the VMWare community program, work is ongoing to develop a number
81 of VMWare images where an entire Catalyst development environment has
82 already been installed, complete with database engines and a full
83 complement of Catalyst plugins.
87 Frank Speiser's Amazon EC2 Catalyst SDK
89 There are currently two flavors of publicly available Amazon Machine
90 Images (AMI) that contain all the dependencies you'd need to get a
91 Catalyst development environment,with all the trimmings, up and
92 running within minutes.
94 Once you obtain an Amazon Elastic Cloud Computing account available
96 L<http://www.amazon.com/EC2-AWS-Service-Pricing/b/ref=sc_fe_l_2?ie=UTF8&node=201590011>,
97 you can literally get a Catalyst development instance up and running
98 in less than 5 minutes.
100 The current AMIs that are available are here in abbreviated form:
102 IMAGE ami-bdbe5ad4 developer-tools/Debian-Etch_Catalyst_DBIC_TT.manifest.xml
103 IMAGE ami-9fbe5af6 developer-tools/Fedora8-Catalyst_DBIC_TT.manifest.xml
105 You can run the instances according to the Amazon documentation, as follows:
107 ec2-run-instances <ami here> -k gsg-keypair
109 Refer to the Amazon EC2 documentation from the "Amazon Web Services"
110 section of the L<Amazon.com| Amazon.com> web site for further
113 You can currently choose between ready-made SDKs on Fedora8 and Debian
114 Etch. Both machine images include Catalyst, DBIx::Class,
115 Template::Toolkit, Moose, the mysql and postgresql databases, as well
116 as subversion source control. The Debian Etch machine instance also
117 includes svk and git.
119 Just run the installation instructions contained in this manual and
126 In addition to the "all-in-one" approaches mentioned above, there are a
127 variety of other installation techniques:
135 The traditional way to install Catalyst is directly from CPAN using the
136 C<Task::Catalyst> bundle and C<Catalyst::Devel>:
138 $ perl -MCPAN -e 'install Task::Catalyst'
139 $ perl -MCPAN -e 'install Catalyst::Devel'
141 Unless you have a particularly complete set of Perl modules already
142 installed, be prepared for a large number of nested dependencies.
148 For users of Gentoo, see
149 C<http://gentoo-wiki.com/HOWTO_Catalyst_Framework> for automated
150 installations. In short, simply mount the portage overlay and type
151 C<emerge catalystframework>.
157 FreeBSD users can get up and running quickly by typing C<cd
158 /usr/ports/www/p5-Catalyst-Devel && make install>, or C<portinstall
159 p5-Catalyst-Devel> if C<portinstall> is installed on your system.
165 Windows users can take advantage of the PPM tool that comes with
166 ActivePerl to jumpstart their Catalyst environment. Directions are
167 available at L<http://catalyst.infogami.com/install/windows>.
171 Subversion Repository
173 Catalyst uses Subversion for version control. To checkout the latest:
175 $ svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/
179 B<NOTE:> Although all of the above methods can be used to install a base
180 Catalyst system, only the VMWare image is likely to have all of the
181 plugins and modules you need to use Catalyst properly. When you start
182 the C<script/myapp_server.pl> development server, it will tell you about
183 any modules that are missing. To add them, type something along the
184 lines of the following (C<Catalyst::Model::DBIC::Schema> is used here as
185 a representative example):
187 # perl -MCPAN -e 'install Catalyst::Model::DBIC::Schema'