lib/Catalyst/Manual/Installation.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Installation - Catalyst Installation
   4
   5 =head1 DESCRIPTION
   6
   7 How to install Catalyst.
   8
   9 =head1 INSTALLATION
  10
  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.
  13
  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.
  25
  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.
  29
  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>.
  39
  40 =over 4
  41
  42 =item *
  43
  44 Matt Trout's C<cat-install> script
  45
  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
  55 installation.
  56
  57 =item *
  58
  59 Chris Laco's CatInABox
  60
  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
  69 other plugins.
  70
  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>.
  75
  76 =item *
  77
  78 Pre-Built VMWare Images
  79
  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.
  84
  85 =item *
  86
  87 Frank Speiser's Amazon EC2 Catalyst SDK
  88
  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.
  93
  94 Once you obtain an Amazon Elastic Cloud Computing account available
  95 here:
  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.
  99
 100 The current AMIs that are available are here in abbreviated form:
 101
 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
 104
 105 You can run the instances according to the Amazon documentation, as follows:
 106
 107   ec2-run-instances <ami here> -k gsg-keypair
 108
 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
 111 assistance.
 112
 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.
 118
 119 Just run the installation instructions contained in this manual and
 120 go.
 121
 122 =back
 123
 124 =head2 OTHER METHODS
 125
 126 In addition to the "all-in-one" approaches mentioned above, there are a
 127 variety of other installation techniques:
 128
 129 =over 4
 130
 131 =item *
 132
 133 CPAN
 134
 135 The traditional way to install Catalyst is directly from CPAN using the
 136 C<Task::Catalyst> bundle and C<Catalyst::Devel>:
 137
 138     $ perl -MCPAN -e 'install Task::Catalyst'
 139     $ perl -MCPAN -e 'install Catalyst::Devel'
 140
 141 Unless you have a particularly complete set of Perl modules already
 142 installed, be prepared for a large number of nested dependencies.
 143
 144 =item *
 145
 146 Gentoo Linux
 147
 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>.
 152
 153 =item *
 154
 155 FreeBSD
 156
 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.
 160
 161 =item *
 162
 163 Windows ActivePerl
 164
 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>.
 168
 169 =item *
 170
 171 Subversion Repository
 172
 173 Catalyst uses Subversion for version control. To checkout the latest:
 174
 175     $ svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/
 176
 177 =back
 178
 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):
 186
 187     # perl -MCPAN -e 'install Catalyst::Model::DBIC::Schema'
 188     ...
 189