3 Catalyst::Manual::Tutorial::01_Intro - Catalyst Tutorial - Chapter 1: Introduction
8 This is B<Chapter 1 of 10> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
28 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
32 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
36 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
40 L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
44 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
48 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
52 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
59 This tutorial provides a multi-part introduction to the Catalyst Web
60 Framework. It seeks to provide a rapid overview of many of its most
61 commonly used features. The focus is on the real-world best practices
62 required in the construction of nearly all Catalyst applications.
64 Although the primary target of the tutorial is users new to the Catalyst
65 framework, experienced users may wish to review specific sections (for
66 example, how to use DBIC for their model classes, how to add
67 authentication and authorization to an existing application, and/or
70 The most recent code for the tutorial is included on the Tutorial Virtual
71 Machine you can download from:
73 L<http://cattut.shadowcat.co.uk/>
75 See L</STARTING WITH THE TUTORIAL VIRTUAL MACHINE> below for
76 instructions getting and using the VM.
78 Should you wish to download the code directly, you get pull it via the
79 following command (note: will probably be switching to git soon):
81 svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial
83 This will download the most recent code for each chapter of the
84 tutorial into the CatalystTutorial directory on your machine.
86 These reference implementations are provided so that when you follow
87 the tutorial, you can use the code to ensure that your system is set up
88 correctly (which shouldn't be an issue if you use the Tutorial Virtual
89 Machine), :-) and that you have not inadvertently made any typographic
90 errors, or accidentally skipped part of the tutorial.
92 B<NOTE: You can use any Perl-supported OS and environment to run
93 Catalyst.> It should make little or no difference to Catalyst's
94 operation, B<but this tutorial has been written using the Debian-based
95 Tutorial Virtual Machine> that you can download and use to work through
96 the full tutorial step by step. B<WE STRONGLY RECOMMEND THAT YOU USE
97 THE VIRTUAL MACHINE IMAGE TO WORK THROUGH THE TUTORIAL> to avoid issues
98 that may crop up if you are working with a different configuration. We
99 have tested the Tutorial Virtual Machine to make sure all of the
100 examples work correctly, but it is hard to guarantee this on other
101 platforms and versions.
103 If you would prefer to install directly from CPAN and not use the
104 Tutorial Virtual machine, you can download the example program and all
105 the necessary dependencies to your local machine by installing the
106 C<Task::Catalyst::Tutorial> distribution:
108 cpan Task::Catalyst::Tutorial
110 This will also test to make sure the dependencies are working. If you
111 have trouble installing these, please ask for help on the #catalyst
112 IRC channel, or the Catalyst mailing list.
114 Subjects covered by the tutorial include:
120 A simple application that lists and adds books.
124 The use of L<DBIx::Class> (DBIC) for the model (including
125 some of the more advanced techniques you will probably want to use in
130 How to write CRUD (Create, Read, Update, and Delete) operations in
135 Authentication ("auth").
139 Role-based authorization ("authz").
143 Attempts to provide an example showing current (5.9) Catalyst
148 The use of Template Toolkit (TT).
152 Useful techniques for troubleshooting and debugging Catalyst
157 The use of SQLite as a database (with code also provided for MySQL and
158 PostgreSQL). (Note: Because we make use of the DBIx::Class Object
159 Relational Mapping [ORM] layer, out our application will be database
160 agnostic and can easily be used by any of the databases supported by
165 The use of L<HTML::FormFu> or L<HTML::FormHandler>
166 for automated form processing and validation.
170 This tutorial makes the learning process its main priority. For
171 example, the level of comments in the code found here would likely be
172 considered excessive in a "normal project." Because of their contextual
173 value, this tutorial will generally favor inline comments over a
174 separate discussion in the text. It also deliberately tries to
175 demonstrate multiple approaches to various features (in general, you
176 should try to be as consistent as possible with your own production
179 Furthermore, this tutorial tries to minimize the number of controllers,
180 models, TT templates, and database tables. Although this does result in
181 things being a bit contrived at times, the concepts should be applicable
182 to more complex environments. More complete and complicated example
183 applications can be found at
184 L<http://wiki.catalystframework.org/wiki/resources/catalystexamples> and
185 in the C<examples> area of the Catalyst Subversion repository at
186 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
189 =head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE
191 The steps below briefly outline how you can download the Tutorial
192 Virtual Machine. This document uses the term "host machine" to refer to
193 the physical machine where you will run the virtualization software and
194 boot up the VM. The terms "guest machine" or just "VM" refer to the
195 virtual machine itself -- the thing where you actually do the tutorial
196 and that you boot up on the "host machine".
198 Also, to reduce download size, the Tutorial VM just includes a minimal
199 command-line environment. In general, it is expected that people will
200 boot up the Tutorial VM on their main desktop (the "host machine" using
201 the terminology above) and then use that main desktop machine to SSH and
202 web browse into the "guest VM" as they work through the tutorial. If
203 you wish to install X-Windows (or any other packages), just use the
204 C<aptitude> (or C<apt-get>) Debian commands.
211 Download a Tutorial Virtual Machine image from
212 L<http://cattut.shadowcat.co.uk/>
214 B<A big thanks to Shadowcat Systems for hosting the virtual machines>
215 B<(and everything else they do for the Perl community)!>
219 Uncompress the image:
221 tar zxvf CatalystTutorial.tgz
225 Boot the virtual machine using a tool like VMWare Player
226 L<http://www.vmware.com/products/player> or VirtualBox
227 L<http://www.virtualbox.org/>.
231 Once you get a login prompt, enter the username B<root> and a password
232 for C<catalyst>. You should now be at a prompt that looks like:
241 Type "C<ifconfig>" to get the IP address assigned to the virtual
242 machine. You should get output along the lines of:
244 eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69
245 inet addr:192.168.0.12 Bcast:192.168.0.255 Mask:255.255.255.0
248 You want the IP address on the second line below the C<eth0> interface.
249 The image it design to automatically use a DHCP-assigned address.
252 Try to ping this IP address from your "host machine" (main desktop):
255 MainComputer:~$ ping 192.168.0.12
256 PING 192.168.0.12 (192.168.0.12) 56(84) bytes of data.
257 64 bytes from 192.168.0.12: icmp_req=1 ttl=255 time=4.97 ms
258 64 bytes from 192.168.0.12: icmp_req=2 ttl=255 time=3.43 ms
262 B<Note:> The ping above is being originated B<from> your B<host machine>
263 (main desktop) and going B<to> your guest B<virtual machine>, not the
266 If you are not seeing a valid IP address or it's not responding to pings
267 (for example, you get error messages along the lines of "Request timed
268 out", "100% packet loss", or "Destination Host Unreachable"), there
269 could be a few network-related issues you might need to sort out. See
270 the section below L</Sorting Out Virtual Machine Network-Related Issues>
271 for additional information and troubleshooting advice.
273 B<Note:> Remember this IP address... you will be using it throughout the
279 B<From your main desktop machine>, open an SSH client and connect to the
280 IP address found in the previous step. You should get a login prompt
281 (accept the SSH key if you get a warning message about that). Login
282 with the same username and password as we used in Step 4: B<root> /
293 B<Using the SSH session>, change to the sample code directory for
294 Chapter 3 included with the Tutorial Virtual Machine and start the
295 Catalyst Development Server:
297 $ cd Final/Chapter03/MyApp
298 $ perl scripts/myapp_server
302 B<From your main desktop machine> (the "host machine"), open a web
303 browser and go to B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP
304 address to your virtual machine that you looked up in Step 5. For
305 example, if your virtual machine is using the IP address
306 C<192.168.0.12>, you would put the following URL into your web browser:
308 http://192.168.0.12:3000/
310 Make sure you don't forget the B<:3000> to use port 3000 instead of the
311 usual port 80 that is used by HTTP by default.
313 You should get a Catalyst Welcome Screen. If you do, feel free to jump
314 right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
315 of the tutorial. If you don't go get the Catalyst Welcome Screen, go
316 back and carefully check each of the steps above.
320 B<Optional:> The VI/VIM editor is already installed on the Tutorial
321 Virtual Machine. In order to reduce the size of the download, Emacs is
322 not pre-installed. Since people obviously have very strong opinions
323 about which editor is best, :-) Debian fortunately make it very easy to
326 $ aptitude install emacs
331 You may note that the Tutorial Virtual Machine uses L<local::lib> so
332 that the Perl modules are run from ~/perl5 (in this case, /root/perl5)
333 vs. the usual location of your "system Perl". We recommend that you
334 also consider using this very handy module. It can greatly ease the
335 process of maintaining and testing different combinations or Perl
336 modules across development, staging, and production servers. (The
337 "relocatable Perl" feature can also be used to to run both the modules
338 B<and> Perl itself from your home directory [or any other directory you
342 =head2 Sorting Out Virtual Machine Network-Related Issues
344 In general, using a virtual machine to work through the tutorial is
345 *much* easier than trying to do it in other environments, especially if
346 you are new to Catalyst (or Perl or CPAN or ...). However, it's
347 possible that you could run into a few network-related issues. The good
348 news is that there is lots of information about the issue available via
349 search engines on the Internet. Here is some background information to
352 In Step 5 of the prior section above, we assumed that a "Bridged Mode"
353 configuration and DHCP will work (it should for most people). If DHCP
354 is not working or is not available in your location, most virtual
355 machine "host" environments let you select between one of several
356 different types of networking between the "guest" and the "host"
363 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
364 in the VM acting like another device on your network that will get a
365 different DHCP IP address than the host machine. The advantage of this
366 approach, is that you can easily SSH and web browse to the guest virtual
367 machine. In general, this is the best option if you want to be able to
368 boot up the VM and then use your SSH client and web browser from your
369 main machine to connect into the virtual machine.
371 In some environments, you might have better luck with "NAT" (Network
372 Address Translation) mode. With this configuration, the guest VM shares
373 the same IP address as the host machine. The downside of this approach
374 is that special configuration is required if you want to be able to SSH
375 or web browse to the guest VM. The NAT option should automatically
376 allow the VM "outbound connection" (e.g., to the Internet if you want to
377 install additional Debian packages), but it requires special
378 configuration if you want to get "inbound connections" that go from some
379 other machine (including the "host machine") into the VM. Some virtual
380 machine host environments let you configure a "static NAT" or "port
381 forwarding" to reach the guest OS, but others omit this functionality.
383 "Local host only" mode let's the guest VM and the host machine talk on a
384 "private subnet" that other devices in your network cannot reach. This
385 can work as long as you don't need to go from the VM to the Internet
386 (for example, to install other Debian packages).
388 Consult the documentation on your virtual machine host environment for
389 help configuring the options above. Here are some links that might
396 L<http://vmfaq.com/entry/34/>
400 L<http://www.vmware.com/support/pubs/player_pubs.html>
404 L<http://www.virtualbox.org/manual/ch06.html>
411 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
413 This tutorial was built using the following resources. Please note that
414 you may need to make adjustments for different environments and versions
415 (note that trailing zeros in version numbers are not significant and may
416 get dropped with some techniques for viewing them; for example, Catalyst
417 v5.80020 might show up as 5.8002):
431 Catalyst::Devel v1.34
439 Catalyst::Model::DBIC::Schema v0.54
443 Template Toolkit v2.22
448 HTML::FormFu -- v0.09004
452 B<NOTE:> You can check the versions you have installed with the
453 following command (note the slash before the space):
455 perl -M<_mod_name_>\ 999
459 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
463 perl -MCatalyst::Devel\ 999
467 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
471 This tutorial will show URLs in the format of C<http://localhost:3000>,
472 but if you are running your web browser from outside the Tutorial
473 Virtual Machine, you will want to substitute the IP address of your VM
474 for the C<localhost> in the URLs (again, you can get the IP address for
475 eth0 from the C<ifconfig> command). For example, if your VM has an
476 IP address of 192.168.0.12, you will want to use a base URL of
477 C<http://192.168.0.12:3000>. Note that the development server
478 defaults to port 3000 (you can change with with the "-p" option on the
481 B<Please Note:> Depending on the web browser you are using, you might
482 need to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
483 testing your application at various points (see
484 L<http://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache> for a
485 comprehensive list of options for each browser).
487 Also, the C<-k> B<keepalive option> to the development server can be
488 necessary with some browsers (B<especially Internet Explorer>).
495 This tutorial will primarily focus on SQLite because of its simplicity
496 of installation and use; however, modifications in the script required
497 to support MySQL and PostgreSQL will be presented in the Appendix.
499 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
500 that applications become much more database independent. As such, you
501 will notice that only the C<.sql> files used to initialize the database
502 change between database systems: most of the code generally remains the
506 You can jump to the next chapter of the tutorial here:
507 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
512 Kennedy Clark, C<hkclark@gmail.com>
514 Feel free to contact the author for any errors or suggestions, but the
515 best way to report issues is via the CPAN RT Bug system at
516 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
518 Copyright 2006-2011, Kennedy Clark, under the
519 Creative Commons Attribution Share-Alike License Version 3.0
520 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).