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 svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial
75 This will download the most recent code for each chapter of the
76 tutorial into the CatalystTutorial directory on your machine.
78 B<These reference implementations are provided so that when you follow
79 the tutorial, you can use the code to ensure that your system is set up
80 correctly (which shouldn't be an issue if you use the Tutorial Virtual
81 Machine), :-) and that you have not inadvertently made any typographic
82 errors, or accidentally skipped part of the tutorial.>
84 B<NOTE: You can use any Perl-supported OS and environment to run
85 Catalyst.> It should make little or no difference to Catalyst's
86 operation, B<but this tutorial has been written using the Debian-based
87 Tutorial Virtual Machine that you can download and use to work through
88 the full tutorial step by step. B<WE STRONGLY RECOMMEND THAT YOU USE
89 THE VIRTUAL MACHINE IMAGE TO WORK THROUGH THE TUTORIAL> to avoid issues
90 that may crop up if you are working with a different configuration. We
91 have tested the Tutorial Virtual Machine to make sure all of the
92 examples work correctly, but it is hard to guarantee this on other
93 platforms and versions.
95 If you would prefer to install directly from CPAN and not use the
96 Tutorial Virtual machine, you can download the example program and all
97 the necessary dependencies to your local machine by installing the
98 C<Task::Catalyst::Tutorial> distribution:
100 cpan Task::Catalyst::Tutorial
102 This will also test to make sure the dependencies are working. If you
103 have trouble installing these, please ask for help on the #catalyst
104 IRC channel, or the Catalyst mailing list.
106 Subjects covered by the tutorial include:
112 A simple application that lists and adds books.
116 The use of L<DBIx::Class> (DBIC) for the model (including
117 some of the more advanced techniques you will probably want to use in
122 How to write CRUD (Create, Read, Update, and Delete) operations in
127 Authentication ("auth").
131 Role-based authorization ("authz").
135 Attempts to provide an example showing current (5.9) Catalyst
140 The use of Template Toolkit (TT).
144 Useful techniques for troubleshooting and debugging Catalyst
149 The use of SQLite as a database (with code also provided for MySQL and
150 PostgreSQL). (Note: Because we make use of the DBIx::Class Object
151 Relational Mapping [ORM] layer, out our application will be database
152 agnostic and can easily be used by any of the databases supported by
157 The use of L<HTML::FormFu> or L<HTML::FormHandler>
158 for automated form processing and validation.
162 This tutorial makes the learning process its main priority. For
163 example, the level of comments in the code found here would likely be
164 considered excessive in a "normal project." Because of their contextual
165 value, this tutorial will generally favor inline comments over a
166 separate discussion in the text. It also deliberately tries to
167 demonstrate multiple approaches to various features (in general, you
168 should try to be as consistent as possible with your own production
171 Furthermore, this tutorial tries to minimize the number of controllers,
172 models, TT templates, and database tables. Although this does result in
173 things being a bit contrived at times, the concepts should be applicable
174 to more complex environments. More complete and complicated example
175 applications can be found at
176 L<http://wiki.catalystframework.org/wiki/resources/catalystexamples> and
177 in the C<examples> area of the Catalyst Subversion repository at
178 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
179 ***Todo: update link above?
183 =head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE
185 The steps below briefly outline how you can download the Tutorial
186 Virtual Machine. This document uses the term "host machine" to refer to
187 the physical machine where you will run the virtualization software and
188 boot up the VM. The terms "guest machine" or just "VM" refer to the
189 virtual machine itself -- the thing where you actually do the tutorial
190 and that you boot up on the "host machine".
192 Also, to reduce download size, the Tutorial VM just includes a minimal
193 command-line environment. In general, it is expected that people will
194 boot up the Tutorial VM on their main desktop (the "host machine" using
195 the terminology above) and then use that main desktop machine to SSH and
196 web browse into the "guest VM" as they work through the tutorial. If
197 you wish to install X-Windows (or any other packages), just use the
198 C<aptitude> (or C<apt-get>) Debian commands.
205 Download the C<debian-live-6.0.1-i386-rescue.iso> image from
206 L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/>.
210 Uncompress the image:
212 tar zxvf CatalystTutorial.tgz
216 Boot the virtual machine using a tool like VMWare Player
217 L<http://www.vmware.com/products/player> or VirtualBox
218 L<http://www.virtualbox.org/>.
222 Once you get a login prompt, enter the username B<root> and a password
223 for C<catalyst>. You should now be at a prompt that looks like:
232 Type "C<ifconfig>" to get the IP address assigned to the virtual
233 machine. You should get output along the lines of:
235 eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69
236 inet addr:192.168.0.12 Bcast:192.168.0.255 Mask:255.255.255.0
239 You want the IP address on the second line below the C<eth0> interface.
240 The image it design to automatically use a DHCP-assigned address.
243 Try to ping this IP address from your "host machine" (main desktop):
246 MainComputer:~$ ping 192.168.0.12
247 PING 192.168.0.12 (192.168.0.12) 56(84) bytes of data.
248 64 bytes from 192.168.0.12: icmp_req=1 ttl=255 time=4.97 ms
249 64 bytes from 192.168.0.12: icmp_req=2 ttl=255 time=3.43 ms
253 B<Note:> The ping above is being originated B<from> your B<host machine>
254 (main desktop) and going B<to> your guest B<virtual machine>, not the
257 If you are not seeing a valid IP address or it's not responding to pings
258 (for example, you get error messages along the lines of "Request timed
259 out", "100% packet loss", or "Destination Host Unreachable"), there
260 could be a few network-related issues you might need to sort out. See
261 the section below L<Sorting Out Virtual Machine Network-Related Issues>
262 for additional information and troubleshooting advice.
264 L<Note:> Remember this IP address... you will be using it throughout the
270 B<From your main desktop machine>, open an SSH client and connect to the
271 IP address found in the previous step. You should get a login prompt
272 (accept the SSH key if you get a warning message about that). Login
273 with the same username and password as we used in Step 4: B<root> /
284 B<Using the SSH session>, change to the sample code directory for
285 Chapter 3 included with the Tutorial Virtual Machine and start the
286 Catalyst Development Server:
288 $ cd Final/Chapter03/MyApp
289 $ perl scripts/myapp_server
293 B<From your main desktop machine> (the "host machine"), open a web
294 browser and go to B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP
295 address to your virtual machine that you looked up in Step 5. For
296 example, if your virtual machine is using the IP address
297 C<192.168.0.12>, you would put the following URL into your web browser:
299 http://192.168.0.12:3000/
301 Make sure you don't forget the B<:3000> to use port 3000 instead of the
302 usual port 80 that is used by HTTP by default.
304 You should get a Catalyst Welcome Screen. If you do, feel free to jump
305 right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
306 of the tutorial. If you don't go get the Catalyst Welcome Screen, go
307 back and carefully check each of the steps above.
311 B<Optional:> The VI/VIM editor is already installed on the Tutorial
312 Virtual Machine. In order to reduce the size of the download, Emacs is
313 not pre-installed. Since people obviously have very strong opinions
314 about which editor is best, :-) Debian fortunately make it very easy to
317 $ aptitude install emacs
322 You may note that the Tutorial Virtual Machine uses L<local::lib> so
323 that the Perl modules are run from ~/perl5 (in this case, /root/perl5)
324 vs. the usual location of your "system Perl". We recommend that you
325 also consider using this very handy module. It can greatly ease the
326 process of maintaining and testing different combinations or Perl
327 modules across development, staging, and production servers. (The
328 "relocatable Perl" feature can also be used to to run both the modules
329 B<and> Perl itself from your home directory [or any other directory you
333 =head2 Sorting Out Virtual Machine Network-Related Issues
335 In general, using a virtual machine to work through the tutorial is
336 *much* easier than trying to do it in other environments, especially if
337 you are new to Catalyst (or Perl or CPAN or ...). However, it's
338 possible that you could run into a few network-related issues. The good
339 news is that there is lots of information about the issue available via
340 search engines on the Internet. Here is some background information to
343 In Step 5 of the prior section above, we assumed that a "Bridged Mode"
344 configuration and DHCP will work (it should for most people). If DHCP
345 is not working or is not available in your location, most virtual
346 machine "host" environments let you select between one of several
347 different types of networking between the "guest" and the "host"
354 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
355 in the VM acting like another device on your network that will get a
356 different DHCP IP address than the host machine. The advantage of this
357 approach, is that you can easily SSH and web browse to the guest virtual
358 machine. In general, this is the best option if you want to be able to
359 boot up the VM and then use your SSH client and web browser from your
360 main machine to connect into the virtual machine.
362 In some environments, you might have better luck with "NAT" (Network
363 Address Translation) mode. With this configuration, the guest VM shares
364 the same IP address as the host machine. The downside of this approach
365 is that special configuration is required if you want to be able to SSH
366 or web browse to the guest VM. The NAT option should automatically
367 allow the VM "outbound connection" (e.g., to the Internet if you want to
368 install additional Debian packages), but it requires special
369 configuration if you want to get "inbound connections" that go from some
370 other machine (including the "host machine") into the VM. Some virtual
371 machine host environments let you configure a "static NAT" or "port
372 forwarding" to reach the guest OS, but others omit this functionality.
374 "Local host only" mode let's the guest VM and the host machine talk on a
375 "private subnet" that other devices in your network cannot reach. This
376 can work as long as you don't need to go from the VM to the Internet
377 (for example, to install other Debian packages).
379 Consult the documentation on your virtual machine host environment for
380 help configuring the options above. Here are some links that might
387 L<VMFAQ.com|http://vmfaq.com/entry/34/>
391 L<VMWare Player Docs|http://www.vmware.com/support/pubs/player_pubs.html>
395 L<Virtual Box Documentation|http://www.virtualbox.org/manual/ch06.html>
402 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
404 This tutorial was built using the following resources. Please note that
405 you may need to make adjustments for different environments and versions
406 (note that trailing zeros in version numbers are not significant and may
407 get dropped with some techniques for viewing them; for example, Catalyst
408 v5.80020 might show up as 5.8002):
422 Catalyst::Devel v1.34
430 Catalyst::Model::DBIC::Schema v0.54
434 Template Toolkit v2.22
439 HTML::FormFu -- v0.09004
443 B<NOTE:> You can check the versions you have installed with the
444 following command (note the slash before the space):
446 perl -M<_mod_name_>\ 999
450 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
454 perl -MCatalyst::Devel\ 999
458 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
462 This tutorial will show URLs in the format of C<http://localhost:3000>,
463 but if you are running your web browser from outside the Tutorial
464 Virtual Machine, you will want to substitute the IP address of your VM
465 for the C<localhost> in the URLs (again, you can get the IP address for
466 eth0 from the C<ifconfig> command). For example, if your VM has an
467 IP address of 192.168.0.12, you will want to use a base URL of
468 C<http://192.168.0.12:3000>. Note that the development server
469 defaults to port 3000 (you can change with with the "-p" option on the
472 B<Please Note:> Depending on the web browser you are using, you might need
473 to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
474 testing your application at various points (see
475 L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
476 list of options for each browser). Also, the C<-k> keepalive option to
477 the development server can be necessary with some browsers (especially
485 This tutorial will primarily focus on SQLite because of its simplicity
486 of installation and use; however, modifications in the script required
487 to support MySQL and PostgreSQL will be presented in the Appendix.
489 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
490 that applications become much more database independent. As such, you
491 will notice that only the C<.sql> files used to initialize the database
492 change between database systems: most of the code generally remains the
496 You can jump to the next chapter of the tutorial here:
497 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
502 Kennedy Clark, C<hkclark@gmail.com>
504 Please report any errors, issues or suggestions to the author. The
505 most recent version of the Catalyst Tutorial can be found at
506 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
508 Copyright 2006-2010, Kennedy Clark, under the
509 Creative Commons Attribution Share-Alike License Version 3.0
510 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).