Add warning to people making tutorial updates
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / 01_Intro.pod
d442cc9f 1=head1 NAME
3ab6187c 3Catalyst::Manual::Tutorial::01_Intro - Catalyst Tutorial - Chapter 1: Introduction
d442cc9f 4
6=head1 OVERVIEW
4b4d3884 8This is B<Chapter 1 of 10> for the Catalyst tutorial.
d442cc9f 9
10L<Tutorial Overview|Catalyst::Manual::Tutorial>
12=over 4
14=item 1
3ab6187c 16B<01_Introduction>
d442cc9f 17
18=item 2
3ab6187c 20L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
d442cc9f 21
22=item 3
3ab6187c 24L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
d442cc9f 25
26=item 4
3ab6187c 28L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
d442cc9f 29
30=item 5
3ab6187c 32L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
d442cc9f 33
34=item 6
3ab6187c 36L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
d442cc9f 37
38=item 7
3ab6187c 40L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
d442cc9f 41
42=item 8
3ab6187c 44L<Testing|Catalyst::Manual::Tutorial::08_Testing>
d442cc9f 45
46=item 9
3ab6187c 48L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
1def4a20 49
50=item 10
3ab6187c 52L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
d442cc9f 53
1def4a20 56
d442cc9f 57=head1 DESCRIPTION
ffeb7448 59This tutorial provides a multi-part introduction to the Catalyst web
d442cc9f 60framework. It seeks to provide a rapid overview of many of its most
61commonly used features. The focus is on the real-world best practices
62required in the construction of nearly all Catalyst applications.
64Although the primary target of the tutorial is users new to the Catalyst
65framework, experienced users may wish to review specific sections (for
1def4a20 66example, how to use DBIC for their model classes, how to add
8168726b 67authentication and authorization to an existing application, and/or
68form management).
d442cc9f 69
70You can obtain the code for all the tutorial examples from the
71catalyst subversion repository by issuing the command:
028b4e1a 73 svn co CatalystTutorial
d442cc9f 74
75b13da6 75This will download the most recent code for each chapter of the
76tutorial into the CatalystTutorial directory on your machine.
d442cc9f 77
3d9ae335 78B<These reference implementations are provided so that when you follow
79the tutorial, you can use the code from the subversion repository to
80ensure that your system is set up correctly, and that you have not
81inadvertently made any typographic errors, or accidentally skipped
82part of the tutorial.>
8168726b 84B<NOTE: You can use any Perl-supported OS and environment to run
85Catalyst.> It should make little or no difference to Catalyst's
a6b4cff5 86operation, B<but this tutorial has been written using the Debian 6 Live
8168726b 87CD> because that represents a quick and easy way for most people to try
88out Catalyst with virtually zero setup time and hassles. Also, the
89tutorial has been tested to work correctly with the versions of Catalyst
90and all the supporting modules in Debian 6 (see "VERSIONS AND
91CONVENTIONS USED IN THIS TUTORIAL" below for the specific versions for
92some of the key modules), so B<if you think you might be running into an
93issue related to versions> (for example, a module changed its behavior
94in a newer version or a bug was introduced), B<it might be worth giving
95Debian 6 a try>.
97If you plan to follow along with Debian 6, you can jump down to the
98"Debian" section under L</"CATALYST INSTALLATION"> below and it will
99walk you though the setup of a fully functional Catalyst environment. If
100you would prefer to install directly from CPAN, you can download the
101example program and all the necessary dependencies to your local machine
102by installing the C<Task::Catalyst::Tutorial> distribution:
d442cc9f 103
104 cpan Task::Catalyst::Tutorial
106This will also test to make sure the dependencies are working. If you
107have trouble installing these, please ask for help on the #catalyst
108IRC channel, or the Catalyst mailing list.
3533daff 110Subjects covered by the tutorial include:
d442cc9f 111
112=over 4
114=item *
116A simple application that lists and adds books.
118=item *
2217b252 120The use of L<DBIx::Class> (DBIC) for the model (including
8168726b 121some of the more advanced techniques you will probably want to use in
acbd7bdd 122your applications).
d442cc9f 123
124=item *
126How to write CRUD (Create, Read, Update, and Delete) operations in
129=item *
131Authentication ("auth").
133=item *
135Role-based authorization ("authz").
137=item *
8168726b 139Attempts to provide an example showing current (5.9) Catalyst
d442cc9f 141
142=item *
1390ef0e 144The use of Template Toolkit (TT).
d442cc9f 145
146=item *
148Useful techniques for troubleshooting and debugging Catalyst
151=item *
153The use of SQLite as a database (with code also provided for MySQL and
8168726b 154PostgreSQL). (Note: Because we make use of the DBIx::Class Object
444d6b27 155Relational Mapping [ORM] layer, out our application will be database
8168726b 156agnostic and can easily be used by any of the databases supported by
d442cc9f 158
159=item *
2217b252 161The use of L<HTML::FormFu> or L<HTML::FormHandler>
0abc72ed 162for automated form processing and validation.
d442cc9f 163
166This tutorial makes the learning process its main priority. For
167example, the level of comments in the code found here would likely be
1def4a20 168considered excessive in a "normal project." Because of their contextual
d442cc9f 169value, this tutorial will generally favor inline comments over a
170separate discussion in the text. It also deliberately tries to
171demonstrate multiple approaches to various features (in general, you
172should try to be as consistent as possible with your own production
175Furthermore, this tutorial tries to minimize the number of controllers,
176models, TT templates, and database tables. Although this does result in
177things being a bit contrived at times, the concepts should be applicable
178to more complex environments. More complete and complicated example
179applications can be found in the C<examples> area of the Catalyst
180Subversion repository at
8168726b 182***Todo: update link above?
d442cc9f 183
1390ef0e 184
2e73e2be 185=head1 QUICK START
8168726b 187For those who want to get going quickly, here is a short "cookbook-style
188recipe" to quickly get you up and running. Although there are many
189different ways to get a Catalyst environment going, this tutorial has
a6b4cff5 190been written with and tested against the Debian 6 Live CD, using the
191steps in this Quick Start.
2e73e2be 192
8168726b 193If you want, you can follow the directions in this section and then jump
194right to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics> of
195the tutorial. However, it would be a good idea to come back and read the
196sections below the Quick Start when you have time. Or, continue reading
197those other sections for suggestions if you do not wish to use the
198Debian 6 Live CD.
2e73e2be 199
2e73e2be 200=over 4
202=item 1
8168726b 204Download the C<debian-live-6.0.1-i386-rescue.iso> image from
2e73e2be 206
207=item 2
209Boot this disk, either in a physical machine, or possibly some sort
8168726b 210of virtual machine (using a VM can be a very handy way to practice).
2e73e2be 211
212=item 3
214Select "C<Live>" from the initial boot menu.
216=item 4
218At the "C<user@debian:~$>" prompt, type:
220 sudo aptitude -y install subversion
222=item 5
224If you want to be able to remotely SSH to this system, set a
a6b4cff5 225password for root (you might want to do "dpkg -l | grep openssh-server"
226to be sure the ISO image you downloaded has the SSH daemon installed...
227if it's missing, do a "sudo aptitude -y install openssh-server"):
2e73e2be 228
229 sudo passwd
230 ...
232=item 6
234Add the "unstable" Debian package repository:
236 sudo vi /etc/apt/sources.list
238Add the following line to the bottom of this file:
240 deb unstable main
242=item 7
244Install Catalyst and related libraries:
246 sudo aptitude update
a5628822 247 sudo aptitude -y install libcatalyst-perl libdatetime-format-sqlite-perl \
248 libdbix-class-encodedcolumn-perl sqlite3 libcatalyst-modules-perl \
249 libperl6-junction-perl libcatalyst-modules-extra-perl \
250 libdbix-class-timestamp-perl
2e73e2be 251 sudo aptitude clean
253=item 8
255Test example code:
257 mkdir test
258 cd test
259 svn co
260 cd MyApp_Chapter8/MyApp
261 CATALYST_DEBUG=0 prove -wl t
262 cd
269This tutorial was built using the following resources. Please note that
a6b4cff5 270you may need to make adjustments for different environments and versions
271(note that trailing zeros in version numbers are not significant and may
272get dropped with some techniques for viewing them; for example, Catalyst
273v5.80020 might show up as 5.8002):
d442cc9f 274
275=over 4
277=item *
95968b61 279Debian 6 (Squeeze)
d442cc9f 280
281=item *
95968b61 283Catalyst v5.80025
dd88c3b6 284
22a67212 285=item *
dd88c3b6 286
95968b61 287Catalyst::Devel v1.28
d442cc9f 288
289=item *
95968b61 291DBIx::Class v0.08123
d442cc9f 292
fce83e5f 293=item *
95968b61 295Catalyst::Model::DBIC::Schema v0.41
2e73e2be 296
297=item *
95968b61 299Template Toolkit v2.22
fce83e5f 300
2e73e2be 301
d442cc9f 302=item *
95968b61 304HTML::FormFu -- v0.07002
2e73e2be 305
d442cc9f 306=item *
865d3efb 308B<NOTE:> You can check the versions you have installed with the
95968b61 309following command (note the slash before the space):
311 perl -M<_mod_name_>\ 999
865d3efb 314
f63a9a2b 315 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
865d3efb 316
317For example:
865d3efb 318
95968b61 319 perl -MCatalyst::Devel\ 999
444d6b27 320
323 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
d442cc9f 324
325=item *
8168726b 327This tutorial will assume that the web browser is located on the same
328system where the Catalyst development server is running, and therefore
329use a URL of C<http://localhost:3000> (the Catalyst development server
a6b4cff5 330defaults to port 3000, but can be changed with the "-p" option to the
331development server). If you are running Perl on a different box than
8168726b 332where your web browser is located (or using a different port number via
333the C<-p> I<port_number> option to the development server), then you
334will need to update the URL you use accordingly.
336Please Note: Depending on the web browser you are using, you might need
337to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
338testing your application at various points (see
339L<> for a comprehensive
340list of options for each browser). Also, the C<-k> keepalive option to
341the development server can be necessary with some browsers (especially
342Internet Explorer). ***Todo: is this still true?
d442cc9f 343
1390ef0e 346
d442cc9f 347=head1 CATALYST INSTALLATION
8168726b 349Although Catalyst installation has been a challenge in the past, the
350good news is that there are a growing number of options to eliminate (or
351at least dramatically simplify) this concern. Although a compelling
352strength of Catalyst is that it makes use of many of the modules in the
353vast repository that is CPAN, this can complicate the installation
354process if you approach it in the wrong way. Consider the following
355suggestions on the most common ways to get started with a Catalyst
356development environment:
1def4a20 357
358=over 4
360=item *
acbd7bdd 362Debian
8168726b 364The Debian 6 Live CD represents a great way for newcomers to experiment
365with Catalyst. As a "live CD," you can simple boot from the CD, run a
366few commands, and in a matter of minutes you should have a fully
367function environment in which do this tutorial. B<The tutorial was fully
368tested to work under Debian 6. Although it SHOULD work under any
369Catalyst installation method you might choose, it can be hard to
370guarantee this.>
acbd7bdd 371
372=over 4
374=item *
8168726b 376Download one of the ISO files from
378(the current version at the time this was written was 6.0.1). You can
379pick any one of the live CD variations will work, but you may wish to
380consider the following points:
acbd7bdd 381
382=over 4
384=item *
8168726b 386"C<debian-live-6.0.1-i386-rescue.iso>" is probably the best all-around
387option for most people because it includes many extra tools such as the
388GCC compiler, therefore saving RAM (every package you need to install
a6b4cff5 389when running from a Live CD consumes memory because RAM disk is being
390used in lieu of real disk space). When initially booting under this
391image, you may see some cryptic warning messages having to do with
392various diagnostic tools it tries to load or enable, but you should be
393able to safely ignore these.
acbd7bdd 394
395=item *
8168726b 397"C<debian-live-6.0.1-i386-standard.iso>" is a great option because of
398its compact size, but you will probably need approximately 1 GB of RAM
399in the computer where you will run the tutorial. Because the "standard"
400live CD comes with with a minimal set of tools, we will have to install
401extra packages (such as the GCC compiler), all of which will require RAM
402when running from a live CD.
acbd7bdd 403
404=item *
8168726b 406The other ISO images include different flavors of X-Windows desktop
407managers. You can select one of these if you don't mind the larger
408download size and prefer a graphical environment. Be aware that these
409disks do not come with the extra tools found on the "rescue" image, so
410you will need adequate RAM to be able to install them just as you would
411under the "standard" image. B<Use one of the "graphical" ISO images if
412you want a graphical web browser on the same machine as where you will
413run the tutorial.> (If you are using one of the non- graphical images
414discussed above, you can still use a graphical web browser from another
415machine and point it to your Catalyst development machine.)
acbd7bdd 416
419=item *
421Boot off the CD.
423=item *
425Select "C<Live>" from the initial boot menu.
427=item *
6163536a 429Once the system has booted to a "C<user@debian:~$>" prompt, first
430install the Subversion client in case you want to check out the
431completed chapter example code:
0ed3df53 433 sudo aptitude -y install subversion
6163536a 434
2e73e2be 435If you want to be able to remotely SSH to this system, set a
436password for root:
438 sudo passwd
439 ...
8168726b 441Then enter the following command to add the more current "unstable"
442package repository so we get the latest versions of Catalyst and related
acbd7bdd 444
445 sudo vi /etc/apt/sources.list
447Add the following line to the bottom of this file:
449 deb unstable main
8168726b 451If you are not familiar with VI, you can move to the bottom of this file
452and press the "o" key to insert a new line and type the line above.
453Then press the "Esc" key followed by a colon (":"), the letters "wq" and
454then the "Enter" key. The rest of the tutorial will assume that you
455know how to use some editor that is available from the Linux
456command-line environment.
acbd7bdd 457
458=item *
460Install Catalyst:
462 sudo aptitude update
a5628822 463 sudo aptitude -y install libcatalyst-perl libdatetime-format-sqlite-perl \
464 libdbix-class-encodedcolumn-perl sqlite3 libcatalyst-modules-perl \
465 libperl6-junction-perl libcatalyst-modules-extra-perl \
466 libdbix-class-timestamp-perl
468Let it install (normally about a 30 to 90-second operation) and you are
469done. (Note the '\' above. Depending on your environment, you might be
470able to cut and paste the text as shown or need to remove the '\'
fce83e5f 471characters to that the command is all on a single line.)
acbd7bdd 472
473If you are using an image other than the "rescue" ISO, you will also need
474to run the following command to install additional packages:
476 sudo aptitude -y install gcc make libc6-dev
8168726b 478If you are running from the Live CD, you probably also want to free up
acbd7bdd 479some RAM disk space with the following:
481 sudo aptitude clean
8168726b 483NOTE: While the instructions above mention the Live CD because that
484makes it easy for people new to Linux, you can obviously pick a
485different Debian ISO image and install it to your hard drive. Although
486there are many different ways to download and install Debian, the
487"netinst" ISO image (such as "C<debian-500-i386-netinst.iso>" represents
488a great option because it keeps your initial download small (but still
489lets you install anything you want "over the network").
acbd7bdd 490
491Here are some tips if you are running from a live CD and are running
492out of disk space (which really means you are running out of RAM):
494=over 4
496=item *
8168726b 498Always run "C<aptitude clean>" after you install new packages to delete
499the original .deb files (the files installed B<by> the .deb package
500B<will> remain available, just the .deb package itself is deleted).
acbd7bdd 501
502=item *
8168726b 504If you are installing modules from CPAN, you can free up some space with
505"C<rm -rf /root/.cpan/*>" (change "/root/" in the previous command to
506match your home directory or the location where CPAN has been configured
507to perform build operations).
acbd7bdd 508
509=item *
8168726b 511If necessary, you can remove the cached package information with the
512command "C<rm -f /var/lib/apt/lists/*>". You can later pull this
acbd7bdd 513information again via the command "C<aptitude update>".
515=item *
8168726b 517You can save a small amount of space by commenting out the lines in
518C</etc/apt/sources.list> that reference "deb-src" and
519"". If you have already done an "C<aptitude update>"
520with these repositories enabled, you can use the tip in the previous
521bullet to free the space up (and then do another "C<aptitude update>").
acbd7bdd 522
523=item *
8168726b 525Although you can free up space by removing packages you installed since
a6b4cff5 526you last booted (check out "C<aptitude remove _pkg_name_>"), don't bother
8168726b 527trying to remove packages already available at the time of boot. Instead
a6b4cff5 528of freeing up space, it will actual consume I<more> space. (The live CD
8168726b 529uses these "burn in" packages right from the CD disk vs. first loading
530them on the virtual RAM disk. However, if you remove them, the system
531has to update various files, something that I<does> consume some space
532on the virtual RAM disk.)
acbd7bdd 533
538=item *
1def4a20 540Ubuntu
a6b4cff5 542Ubuntu is a popular offshoot of Debian. It provides cutting edge
543versions of many common tools, application and libraries in an
8168726b 544easy-to-run live CD configuration (and because a single download option
545can be used for both live CD and install-to-disk usage, it keeps your
546download options nice and simple). As with Debian 6, you should be able
547to generate a fully function Catalyst environment in a matter of
548minutes. Here are quick instructions on how to use Ubuntu to prepare
549for the tutorial:
d442cc9f 550
551=over 4
553=item *
8168726b 555Download the Ubuntu Desktop edition and boot from the CD and/or image
556file, select your language, and then "Try Ubuntu without any changes to
557your computer."
1def4a20 558
559=item *
8168726b 561Open a terminal session (click "Applications" in the upper-left corner,
562then "Accessories," then "Terminal").
1def4a20 563
564=item *
566Add the 'universe' repositories:
3533daff 568 sudo gedit /etc/apt/sources.list
1def4a20 569
570And remove the comments from the lines under the comments about the
571'universe' repositories.
573=item *
575Install Catalyst:
acbd7bdd 577 sudo aptitude update
578 sudo aptitude install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl libconfig-general-perl
1def4a20 579
8168726b 580Accept all of the dependencies. Done.
2b75577c 581
8168726b 582If you are running from the Live CD, you probably also want to free up
2b75577c 583some disk space with the following:
acbd7bdd 585 sudo aptitude clean
2b75577c 586
8168726b 587NOTE: While the instructions above mention the live CD because that
588makes it easy for people new to Linux, you can obviously also use one of
589the options to install Ubuntu on your drive.
3533daff 590
1def4a20 591=back
593=item *
d442cc9f 595Matt Trout's C<cat-install>
8168726b 597Available at L<>,
598C<cat-install> can be a fairly painless way to get Catalyst up and
a6b4cff5 599running. Just download the script from the link above and type
600C<perl cat-install>. Depending on the speed of your Internet connection
601and your computer, it will probably take 30 to 60 minutes to install
602because it downloads, makes, compiles, and tests every module. But this
603is an excellent way to automate the installation of all the latest
604modules used by Catalyst from CPAN.
ffeb7448 605
d442cc9f 606
607=item *
ffeb7448 609Other Possibilities
611=over 4
613=item *
615OpenBSD Packages
8168726b 617The 2008 Advent Day 4 entry has more information on using OpenBSD
618packages to quickly build a system:
ffeb7448 619L<>.
621=item *
d442cc9f 622
ffeb7448 623NetBSD Package Collection on Solaris
8168726b 625The 2008 Advent Day 15 entry has more information on using C<pkgsrc> and
626NetBSD packages on Solaris:
1435672d 627L<>.
d442cc9f 628
629=item *
ffeb7448 631CatInABox
8168726b 633You can get more information at
634L<> or
2217b252 635L<Perl::Dist::CatInABox>.
ffeb7448 636
0c51850e 637=item *
639Frank Speiser's Amazon EC2 Catalyst SDK
641There are currently two flavors of publicly available Amazon Machine
642Images (AMI) that include all the elements you'd need to begin
643developing in a fully functional Catalyst environment within minutes.
2217b252 644See L<Catalyst::Manual::Installation>
0c51850e 645for more details.
d442cc9f 647=back
ffeb7448 649=back
d442cc9f 651For additional information and recommendations on Catalyst installation,
8168726b 652please refer to
2217b252 653L<Catalyst::Manual::Installation>.
d442cc9f 654
1390ef0e 655
d442cc9f 656=head1 DATABASES
658This tutorial will primarily focus on SQLite because of its simplicity
659of installation and use; however, modifications in the script required
a6b4cff5 660to support MySQL and PostgreSQL will be presented in the Appendix.
d442cc9f 661
a6b4cff5 662B<Note:> One of the advantages of using tools like Catalyst and DBIC is
663that applications become much more database independent. As such, you
664will notice that only the C<.sql> files used to initialize the database
665change between database systems: most of the code generally remains the
d442cc9f 666same.
1390ef0e 668
d442cc9f 669=head1 WHERE TO GET WORKING CODE
8168726b 671Each chapter of the tutorial has complete code available as a tarball in
672the main Catalyst Subversion repository (see the note at the beginning
028b4e1a 673of each part for the appropriate svn command to use).
d442cc9f 674
8168726b 675B<NOTE:> You can run the test cases for the final code through Chapter 8
028b4e1a 676with the following commands:
d442cc9f 677
0ed3df53 678 svn co
679 cd MyApp_Chapter8/MyApp
96a87356 680 CATALYST_DEBUG=0 prove -wl t
d442cc9f 681
2217b252 682If you wish to include the L<HTML::FormFu> section in your tests,
6163536a 683substitute C<MyApp_Chapter9_FormFu> for C<MyApp_Chapter8> in the URL
684above (don't forget to "cd" out of the Ch8 directory if you ran the code above).
acbd7bdd 685
0ed3df53 686 svn co
687 cd MyApp_Chapter9_FormFu/MyApp
96a87356 688 CATALYST_DEBUG=0 prove -wl t
acbd7bdd 689
690You can also fire up the application under the development server that is conveniently
691built in to Catalyst. Just issue this command from the C<MyApp> directory where you
692ran the test suite above:
694 script/
8168726b 696And the application will start. You can try out the application by
697pulling up C<http://localhost:3000> in your web browser (as mentioned
698earlier, change C<localhost> to a different IP address or DNS name if
699you are running your web browser and your Catalyst development on
700different boxes). We will obviously see more about how to use the
701application as we go through the remaining chapters of the tutorial, but
702for now you can log in using the username "test01" and a password of
acbd7bdd 703"mypass".
d442cc9f 705
706=head1 AUTHOR
708Kennedy Clark, C<>
8168726b 710Please report any errors, issues or suggestions to the author. The
711most recent version of the Catalyst Tutorial can be found at
59884771 712L<>.
d442cc9f 713
ec3ef4ad 714Copyright 2006-2010, Kennedy Clark, under the
715Creative Commons Attribution Share-Alike License Version 3.0
865d3efb 716(L<>).