=head1 NAME
-Catalyst::Manual::Installation Catalyst Installation
-
-
+Catalyst::Manual::Installation - Catalyst Installation
=head1 DESCRIPTION
-This section of the Catalyst tutorial looks at a number of items required to first get going with Catalyst development.
-
-
+How to install Catalyst.
=head1 INSTALLATION
-On one hand, Catalyst gains immediate power and flexibility through is use of CPAN (the Comprehensive Perl Archive Network, an enormous global repository containing over 10,000 free modules). On the other hand, Catalyst's reliance on CPAN can complicate initial installations. Fortunately, there are a growing number of methods that can dramatically ease this undertaking:
+One of the frequent problems reported by new users of Catalyst is that
+it can be extremely time-consuming and difficult to install.
+
+One of the great strengths of Perl as a programming language is its use
+of CPAN, the Comprehensive Perl Archive Network, an enormous global
+repository containing over 10,000 free modules. For almost any basic
+task--and a very large number of non-basic ones--there is a module on
+CPAN that will help you. Catalyst has taken advantage of this, and uses
+a very large number of CPAN modules, rather than reinventing the wheel
+over and over again. On the one hand, Catalyst gains power and
+flexibility through this re-use of existing code. On the other hand,
+Catalyst's reliance on CPAN can complicate initial installations,
+especially in shared-hosting environments where you, the user, do not
+have easy control over what versions of other modules are installed.
+
+It is worth stressing that the difficulties found in installing Catalyst
+are caused not by anything intrinsic to Catalyst itself, but rather by
+the interrelated dependencies of a large number of required modules.
+
+Fortunately, there are a growing number of methods that can dramatically
+ease this undertaking. Note that for many of these, you will probably
+need to install additional Catalyst-related modules (especially plugins)
+to do the things you want. As of version 5.70, Catalyst has split into
+two packages, L<Catalyst::Runtime>, which includes the core elements
+necessary to deploy a Catalyst application, and L<Catalyst::Devel>,
+which includes the Helpers and other things necessary or useful for
+developing Catalyst applications. In a purely deployment environment
+you can omit L<Catalyst::Devel>.
=over 4
=item *
-Matt Trouts C<cat-install>
+Matt Trout's C<cat-install> script
-Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>, C<cat-install> can be a quick and painless way to get Catalyst up and running. Just download the script from the link above and type C<perl cat-install>.
+Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
+C<cat-install> can be a quick and painless way to get Catalyst up and
+running on your system. Just download the script from the link above
+and type C<perl cat-install>. This script automates the process of
+installing Catalyst itself and its dependencies, with bits of overriding
+so that the process does not require user interaction. C<cat-install>
+installs Catalyst and its dependencies using the L<CPAN> module, so that
+modules are installed the same way you would probably install them
+normally--it just makes it easier. This is a recommended solution for
+installation.
=item *
Chris Laco's CatInABox
-Download the tarball from L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it on your machine. Depending on your OS platform, either run C<start.bat> or C<start.sh>.
+CatInABox is a complete version of Catalyst that is installed locally on
+your system, so that you don't need to go through the effort of doing a
+full install. Simply download the tarball from
+L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
+on your machine. Depending on your OS platform, either run C<start.bat>
+or C<start.sh> to set your bin/PERLLIB paths. This tarball contains
+everything needed to try out Catalyst including Catalyst itself,
+Template Toolkit, several Authentication modules, StackTrace, and a few
+other plugins.
+
+A special Win32 version is available upon request that contains many
+more plugins and pre-compiled modules, including DBIx::Class, DBI,
+SQLite, and Session support. If you are interested in this version,
+please send e-mail to C<claco@chrislaco.com>.
=item *
Pre-Built VMWare Images
-Under the VMWare community program, work is ongoing to develop a number of VMWare images where an entire Catalyst development environment has already been installed, complete with database engines and a full complement of Catalyst plugins.
-
-=back
-
-
-=head2 OTHER METHODS
-
-In addition to the "all-in-one" approaches mentioned above, there are a variety of other installation techniques:
-
-=over 4
+Under the VMWare community program, work is ongoing to develop a number
+of VMWare images where an entire Catalyst development environment has
+already been installed, complete with database engines and a full
+complement of Catalyst plugins.
=item *
-CPAN
-
-The traditional way to install Catalyst is directly from CPAN using C<Task::Catalyst> bundle:
+Frank Speiser's Amazon EC2 Catalyst SDK
- $ perl MCPAN e 'install Task::Catalyst'
+There are currently two flavors of publicly available Amazon Machine
+Images (AMI) that contain all the dependencies you'd need to get a
+Catalyst development environment,with all the trimmings, up and
+running within minutes.
-Unless you have a particularly complete set of Perl modules already installed, be prepared for a large number of nested dependencies.
-
-=item *
-
-Gentoo Linux
+Once you obtain an Amazon Elastic Cloud Computing account available
+here:
+L<http://www.amazon.com/EC2-AWS-Service-Pricing/b/ref=sc_fe_l_2?ie=UTF8&node=201590011>,
+you can literally get a Catalyst development instance up and running
+in less than 5 minutes.
-For users of Gentoo, see C<http://gentoo-wiki.com/HOWTO_Catalyst_Framework> for automated installations. In short, simply mount the portage overlay and type C<emerge catalystframework>.
+The current AMIs that are available are here in abbreviated form:
-=items *
+ IMAGE ami-bdbe5ad4 developer-tools/Debian-Etch_Catalyst_DBIC_TT.manifest.xml
+ IMAGE ami-9fbe5af6 developer-tools/Fedora8-Catalyst_DBIC_TT.manifest.xml
-FreeBSD
+You can run the instances according to the Amazon documentation, as follows:
-FreeBSD users can get up and running quickly by typing C<cd /usr/ports/www/p5-Catalyst && make install>.
+ ec2-run-instances <ami here> -k gsg-keypair
-=item *
+Refer to the Amazon EC2 documentation from the "Amazon Web Services"
+section of the L<Amazon.com| Amazon.com> web site for further
+assistance.
-Windows ActivePerl
+You can currently choose between ready-made SDKs on Fedora8 and Debian
+Etch. Both machine images include Catalyst, DBIx::Class,
+Template::Toolkit, Moose, the mysql and postgresql databases, as well
+as subversion source control. The Debian Etch machine instance also
+includes svk and git.
-Windows users can take advantage of the PPM tool that comes with ActivePerl to jumpstart their Catalyst environment. Directions are available at L<http://catalyst.infogami.com/katalytes/cat_on_windows>.
+Just run the installation instructions contained in this manual and
+go.
=back
-B<NOTE:> Although all of the above methods can be used to install a base Catalyst system, only the VMWare image is likely to have all of the plugins and modules you need to complete this tutorial. When you start the C<script/myapp_server.pl> development server later to run your application, it will tell you about any modules that are missing. To add them, type something along the lines of the following (C<Catalyst::Model::DBIC::Schema> is used here as a representative example):
-
- # perl -MCPAN -e shell
-
- cpan shell -- CPAN exploration and modules installation (v1.87)
- ReadLine support enabled
-
- cpan> install Catalyst::Model::DBIC::Schema
- ...
-
-
-=head2 OTHER ITEMS
+=head2 OTHER METHODS
-Although Catalyst is a very flexible platform that can be used for wide variety of applications, the bulk of Catalyst developers use it to build web applications that set on top of a relational database. Consequently, you will very likely need:
+In addition to the "all-in-one" approaches mentioned above, there are a
+variety of other installation techniques:
=over 4
=item *
-A Web Server
-
-Although Apache is obviously an extremely popular choice, lighttpd has a growing following. Catalyst applications can also be run under IIS.
+CPAN
-=item *
+The traditional way to install Catalyst is directly from CPAN using the
+C<Task::Catalyst> bundle and C<Catalyst::Devel>:
-A Database
+ $ perl -MCPAN -e 'install Task::Catalyst'
+ $ perl -MCPAN -e 'install Catalyst::Devel'
-Although other databases with support for Perl are certainly possible, most Catalyst applications tend to use one of the following:
+Unless you have a particularly complete set of Perl modules already
+installed, be prepared for a large number of nested dependencies.
=item *
-SQLite
+Gentoo Linux
-SQLite is a popular choice for development and testing because it does note require that a database daemon be running or configured. It operates on C<.db> files that are generally located in the directory of your Catalyst application project. More information is available at L<www.sqlite.org>.
+For users of Gentoo, see
+C<http://gentoo-wiki.com/HOWTO_Catalyst_Framework> for automated
+installations. In short, simply mount the portage overlay and type
+C<emerge catalystframework>.
=item *
-MySQL
+FreeBSD
-MySQL is an extremely popular database available at L<www.mysql.com>.
+FreeBSD users can get up and running quickly by typing C<cd
+/usr/ports/www/p5-Catalyst-Devel && make install>, or C<portinstall
+p5-Catalyst-Devel> if C<portinstall> is installed on your system.
=item *
-PostgreSQL
+Windows ActivePerl
-PostgreSQL is a well-respected database available at L<http://www.postgresql.org/>.
+Windows users can take advantage of the PPM tool that comes with
+ActivePerl to jumpstart their Catalyst environment. Directions are
+available at L<http://catalyst.infogami.com/install/windows>.
-=back
+=item *
+
+Subversion Repository
-This tutorial will primarily focus on SQLite because of its simplicity; however, modifications in the script required to support MySQL and PostgreSQL will be presented in Appendix X.
+Catalyst uses Subversion for version control. To checkout the latest:
-B<Note:> One of the advantages of the MVC design patterns is that applications become much more database independent. As such, you will notice that only the C<.sql> files used to initialize the database change between database systems... the Catalyst code all remains the same.
+ $ svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/
=back
+B<NOTE:> Although all of the above methods can be used to install a base
+Catalyst system, only the VMWare image is likely to have all of the
+plugins and modules you need to use Catalyst properly. When you start
+the C<script/myapp_server.pl> development server, it will tell you about
+any modules that are missing. To add them, type something along the
+lines of the following (C<Catalyst::Model::DBIC::Schema> is used here as
+a representative example):
+
+ # perl -MCPAN -e 'install Catalyst::Model::DBIC::Schema'
+ ...
projects / catagits/Catalyst-Runtime.git / blobdiff