=head1 DESCRIPTION
-This tutorial provides a multi-part introduction to the Catalyst web
-framework. It seeks to provide a rapid overview of many of its most
+This tutorial provides a multi-part introduction to the Catalyst Web
+Framework. It seeks to provide a rapid overview of many of its most
commonly used features. The focus is on the real-world best practices
required in the construction of nearly all Catalyst applications.
authentication and authorization to an existing application, and/or
form management).
-You can obtain the code for all the tutorial examples from the
-catalyst subversion repository by issuing the command:
+The most recent code for the tutorial is included on the Tutorial Virtual
+Machine you can download from:
+
+L<http://cattut.shadowcat.co.uk/>
+
+See L</STARTING WITH THE TUTORIAL VIRTUAL MACHINE> below for
+instructions getting and using the VM.
+
+Should you wish to download the code directly, you get pull it via the
+following command (note: will probably be switching to git soon):
svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial
This will download the most recent code for each chapter of the
tutorial into the CatalystTutorial directory on your machine.
-B<These reference implementations are provided so that when you follow
-the tutorial, you can use the code from the subversion repository to
-ensure that your system is set up correctly, and that you have not
-inadvertently made any typographic errors, or accidentally skipped
-part of the tutorial.>
+These reference implementations are provided so that when you follow
+the tutorial, you can use the code to ensure that your system is set up
+correctly (which shouldn't be an issue if you use the Tutorial Virtual
+Machine), :-) and that you have not inadvertently made any typographic
+errors, or accidentally skipped part of the tutorial.
B<NOTE: You can use any Perl-supported OS and environment to run
Catalyst.> It should make little or no difference to Catalyst's
-operation, B<but this tutorial has been written using the Debian 6 Live
-CD> because that represents a quick and easy way for most people to try
-out Catalyst with virtually zero setup time and hassles. Also, the
-tutorial has been tested to work correctly with the versions of Catalyst
-and all the supporting modules in Debian 6 (see "VERSIONS AND
-CONVENTIONS USED IN THIS TUTORIAL" below for the specific versions for
-some of the key modules), so B<if you think you might be running into an
-issue related to versions> (for example, a module changed its behavior
-in a newer version or a bug was introduced), B<it might be worth giving
-Debian 6 a try>.
-
-If you plan to follow along with Debian 6, you can jump down to the
-"Debian" section under L</"CATALYST INSTALLATION"> below and it will
-walk you though the setup of a fully functional Catalyst environment. If
-you would prefer to install directly from CPAN, you can download the
-example program and all the necessary dependencies to your local machine
-by installing the C<Task::Catalyst::Tutorial> distribution:
+operation, B<but this tutorial has been written using the Debian-based
+Tutorial Virtual Machine> that you can download and use to work through
+the full tutorial step by step. B<WE STRONGLY RECOMMEND THAT YOU USE
+THE VIRTUAL MACHINE IMAGE TO WORK THROUGH THE TUTORIAL> to avoid issues
+that may crop up if you are working with a different configuration. We
+have tested the Tutorial Virtual Machine to make sure all of the
+examples work correctly, but it is hard to guarantee this on other
+platforms and versions.
+
+If you would prefer to install directly from CPAN and not use the
+Tutorial Virtual machine, you can download the example program and all
+the necessary dependencies to your local machine by installing the
+C<Task::Catalyst::Tutorial> distribution:
cpan Task::Catalyst::Tutorial
=item *
-The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model (including
+The use of L<DBIx::Class> (DBIC) for the model (including
some of the more advanced techniques you will probably want to use in
your applications).
=item *
-The use of L<HTML::FormFu|HTML::FormFu> or L<HTML::FormHandler|HTML::FormHandler>
+The use of L<HTML::FormFu> or L<HTML::FormHandler>
for automated form processing and validation.
=back
models, TT templates, and database tables. Although this does result in
things being a bit contrived at times, the concepts should be applicable
to more complex environments. More complete and complicated example
-applications can be found in the C<examples> area of the Catalyst
-Subversion repository at
+applications can be found at
+L<http://wiki.catalystframework.org/wiki/resources/catalystexamples> and
+in the C<examples> area of the Catalyst Subversion repository at
L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
-***Todo: update link above?
-=head1 QUICK START
+=head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE
-For those who want to get going quickly, here is a short "cookbook-style
-recipe" to quickly get you up and running. Although there are many
-different ways to get a Catalyst environment going, this tutorial has
-been written with and tested against the Debian 6 Live CD, using the
-steps in this Quick Start.
+The steps below briefly outline how you can download the Tutorial
+Virtual Machine. This document uses the term "host machine" to refer to
+the physical machine where you will run the virtualization software and
+boot up the VM. The terms "guest machine" or just "VM" refer to the
+virtual machine itself -- the thing where you actually do the tutorial
+(and that you boot up on the "host machine").
+
+B<Note:> Throughout the tutorial, we will shows the UNIX shell prompt as
+"C<$>". If you are using the Tutorial VM, the prompt will really be
+"C<catalyst@catalyst:~$>" (where "C<~"> will change to show your
+current directory), but we will keep it short and just use "C<$>".
-If you want, you can follow the directions in this section and then jump
-right to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics> of
-the tutorial. However, it would be a good idea to come back and read the
-sections below the Quick Start when you have time. Or, continue reading
-those other sections for suggestions if you do not wish to use the
-Debian 6 Live CD.
=over 4
=item 1
-Download the C<debian-live-6.0.1-i386-rescue.iso> image from
-L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/>.
+Download a Tutorial Virtual Machine image from
+L<http://cattut.shadowcat.co.uk/>
+
+B<A big thanks to Shadowcat Systems for hosting the virtual machines>
+B<(and everything else they do for the Perl community)!>
=item 2
-Boot this disk, either in a physical machine, or possibly some sort
-of virtual machine (using a VM can be a very handy way to practice).
+Uncompress the image on the "host machine":
+
+ MAINCOMPUTER:~$ tar zxvf CatalystTutorial.tgz
=item 3
-Select "C<Live>" from the initial boot menu.
+Boot the virtual machine using a tool like VMWare Player
+L<http://www.vmware.com/products/player> or VirtualBox
+L<http://www.virtualbox.org/>.
=item 4
-At the "C<user@debian:~$>" prompt, type:
+Once you get a login prompt, enter the username B<catalyst> and a
+password for C<catalyst>. You should now be at a prompt that looks
+like:
- sudo aptitude -y install subversion
+ catalyst login: catalyst
+ Password: catalyst
+ ...
+ catalyst@catalyst:~$
=item 5
-If you want to be able to remotely SSH to this system, set a
-password for root (you might want to do "dpkg -l | grep openssh-server"
-to be sure the ISO image you downloaded has the SSH daemon installed...
-if it's missing, do a "sudo aptitude -y install openssh-server"):
+Type "C<ifconfig>" to get the IP address assigned to the virtual
+machine. You should get output along the lines of:
- sudo passwd
+ eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69
+ inet addr:192.168.0.12 Bcast:192.168.0.255 Mask:255.255.255.0
...
-=item 6
-
-Add the "unstable" Debian package repository:
-
- sudo vi /etc/apt/sources.list
-
-Add the following line to the bottom of this file:
-
- deb http://ftp.us.debian.org/debian/ unstable main
-
-=item 7
-
-Install Catalyst and related libraries:
-
- sudo aptitude update
- sudo aptitude -y install sqlite3 libdbd-sqlite3-perl libcatalyst-perl \
- libcatalyst-modules-perl libdbix-class-timestamp-perl \
- libdatetime-format-sqlite-perl libconfig-general-perl \
- libhtml-formfu-model-dbic-perl libterm-readline-perl-perl \
- libdbix-class-encodedcolumn-perl libperl6-junction-perl \
- libtest-pod-perl
- sudo aptitude clean
-
-=item 8
-
-Test example code:
-
- mkdir test
- cd test
- svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8
- cd MyApp_Chapter8/MyApp
- CATALYST_DEBUG=0 prove -wl t
- cd
-
-=back
-
-
-=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
-
-This tutorial was built using the following resources. Please note that
-you may need to make adjustments for different environments and versions
-(note that trailing zeros in version numbers are not significant and may
-get dropped with some techniques for viewing them; for example, Catalyst
-v5.80020 might show up as 5.8002):
-
-=over 4
-
-=item *
-
-Debian 5 (Lenny)
-
-=item *
-
-Catalyst v5.80020 (note: may show up as '5.8002' without the trailing zero)
-
-=item *
-
-Catalyst::Devel v1.26
-
-=item *
+You want the IP address on the second line below the C<eth0> interface.
+The image it design to automatically use a DHCP-assigned address.
-DBIx::Class v0.08115
-=item *
+Try to ping this IP address from your "host machine" (main desktop):
-Catalyst::Model::DBIC::Schema v0.40
-=item *
+ MAINCOMPUTER:~$ ping 192.168.0.12
+ PING 192.168.0.12 (192.168.0.12) 56(84) bytes of data.
+ 64 bytes from 192.168.0.12: icmp_req=1 ttl=255 time=4.97 ms
+ 64 bytes from 192.168.0.12: icmp_req=2 ttl=255 time=3.43 ms
+ ...
-Template Toolkit v2.20
+B<Note:> The ping above is being originated B<from> your B<host machine>
+(main desktop) and going B<to> your guest B<virtual machine>, not the
+other way around.
-=item *
+If you are not seeing a valid IP address or it's not responding to pings
+(for example, you get error messages along the lines of "Request timed
+out", "100% packet loss", or "Destination Host Unreachable"), there
+could be a few network-related issues you might need to sort out. See
+the section below L</Sorting Out Virtual Machine Network-Related Issues>
+for additional information and troubleshooting advice.
-Catalyst Plugins
+B<Note:> Remember this IP address... you will be using it throughout the
+tutorial.
-The plugins used in this tutorial all have sufficiently stable APIs that
-you shouldn't need to worry about versions. However, there could be
-cases where the tutorial is affected by what version of plugins you
-use. This tutorial has been tested against the following set of plugins:
-=over 4
+=item 6
-=item *
+B<From your main desktop machine>, open an SSH client and connect to the
+IP address found in the previous step. You should get a login prompt
+(accept the SSH key if you get a warning message about that). Login
+with the same username and password as we used in Step 4: B<catalyst> /
+B<catalyst>
-Catalyst::Plugin::Authentication -- v0.10016
+ catalyst login: catalyst
+ Password: catalyst
+ ...
+ catalyst@catalyst:~$
-=item *
-Catalyst::Plugin::Authorization::Roles -- v0.08
+=item 7
-=item *
+B<Using the SSH session>, change to the sample code directory for
+Chapter 3 included with the Tutorial Virtual Machine and start the
+Catalyst Development Server:
-Catalyst::Plugin::ConfigLoader -- v0.27
+ $ cd Final/Chapter03/MyApp
+ $ perl script/myapp_server.pl
-=item *
+=item 8
-Catalyst::Plugin::Session -- v0.29
+B<From your main desktop machine> (the "host machine"), open a web
+browser and go to B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP
+address to your virtual machine that you looked up in Step 5. For
+example, if your virtual machine is using the IP address
+C<192.168.0.12>, you would put the following URL into your web browser:
-=item *
+ http://192.168.0.12:3000/
-Catalyst::Plugin::Session::State::Cookie -- v0.17
+Make sure you don't forget the B<:3000> to use port 3000 instead of the
+usual port 80 that is used by HTTP by default.
-=item *
+You should get a Catalyst Welcome Screen. If you do, feel free to jump
+right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
+of the tutorial. If you don't go get the Catalyst Welcome Screen, go
+back and carefully check each of the steps above.
-Catalyst::Plugin::Session::Store::File -- v0.18
+=item 9
-=item *
+B<Optional:> Also, to reduce download size, the Tutorial VM just
+includes a minimal command-line environment. You are free to use
+Debian's very capable C<apt> package manager to install other packages.
+You will first want to pull the apt cache files with C<aptitude update>
+(or C<apt-get update> if you prefer apt-get).
-Catalyst::Plugin::StackTrace -- v0.11
+The VI/VIM editor is already installed on the Tutorial Virtual Machine.
+In order to reduce the size of the download, Emacs is not pre-installed.
+Since people obviously have very strong opinions about which editor is
+best, :-) fortunately it's very easy to install Emacs:
-=item *
+ $ sudo aptitude update
+ $ sudo aptitude install emacs
-Catalyst::Plugin::Static::Simple -- v0.29
+In general, it is expected that people will
+boot up the Tutorial VM on their main desktop (the "host machine" using
+the terminology above) and then use that main desktop machine to SSH and
+web browse into the "guest VM" as they work through the tutorial. If
+you wish to install X Windows (or any other packages), just use the
+C<aptitude> (or C<apt-get>) Debian commands.
-=back
+For example, to install X Windows with Fluxbox (a lightweight
+WindowManager -- it is great for things like this tutorial since it's
+about 1/10th the size of other common X Windows environments), you can
+do:
-=item *
+ $ sudo aptitude update
+ $ sudo aptitude install xorg fluxbox iceweasel
-HTML::FormFu -- v0.06001
+And then start X Windows from the B<VM Console> with this command:
-=item *
+ $ startx
-B<NOTE:> You can check the versions you have installed with the
-following command:
+Note that if you want to start Fluxbox from an SSH session, you can use
+the C<sudo dpkg-reconfigure x11-common> and select "anybody" from the
+menu. Otherwise, you will need to be on the actual "VM console" to
+start it.
- perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
+If you have a preference for the Gnome desktop environment, you can do:
-For example:
+ $ sudo aptitude update
+ $ sudo aptitude install gnome iceweasel
+ $
+ $ # You can reboot or start with 'startx', we will just reboot here
+ $ reboot
- perl -MCatalyst -e 'print "$Catalyst::VERSION\n";'
+For KDE, just substitute the package name "C<kde>" for "C<gnome>" above.
-or:
+ $ sudo aptitude install kde iceweasel
- perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
+Note that C<iceweasel> is basically used to install Firefox on Debian
+boxes. You can start it under X Windows with either the C<firefox>
+command or the C<iceweasel> command (or use the menus). You can get
+more information on Iceweasel at L<http://wiki.debian.org/Iceweasel>.
-=item *
+Also, you might need to add more memory to your virtual machine if you
+want to run X Windows (or other tools that might require additional
+memory). Consult the documentation for you virtualization software
+for instructions on how to do this (it's usually pretty simple).
-This tutorial will assume that the web browser is located on the same
-system where the Catalyst development server is running, and therefore
-use a URL of C<http://localhost:3000> (the Catalyst development server
-defaults to port 3000, but can be changed with the "-p" option to the
-development server). If you are running Perl on a different box than
-where your web browser is located (or using a different port number via
-the C<-p> I<port_number> option to the development server), then you
-will need to update the URL you use accordingly.
-
-Please Note: Depending on the web browser you are using, you might need
-to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
-testing your application at various points (see
-L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
-list of options for each browser). Also, the C<-k> keepalive option to
-the development server can be necessary with some browsers (especially
-Internet Explorer). ***Todo: is this still true?
=back
-=head1 CATALYST INSTALLATION
-
-Although Catalyst installation has been a challenge in the past, the
-good news is that there are a growing number of options to eliminate (or
-at least dramatically simplify) this concern. Although a compelling
-strength of Catalyst is that it makes use of many of the modules in the
-vast repository that is CPAN, this can complicate the installation
-process if you approach it in the wrong way. Consider the following
-suggestions on the most common ways to get started with a Catalyst
-development environment:
+You may note that the Tutorial Virtual Machine uses L<local::lib> so
+that the Perl modules are run from ~/perl5 (in this case,
+/home/catalyst/perl5) vs. the usual location of your "system Perl". We
+recommend that you also consider using this very handy module. It can
+greatly ease the process of maintaining and testing different
+combinations or Perl modules across development, staging, and production
+servers. (The "relocatable Perl" feature can also be used to to run
+both the modules B<and> Perl itself from your home directory [or any
+other directory you chose]).
+
+B<Note>: Please provide feedback on how the Virtual Machine approach for
+the tutorial works for you. If you have suggestions or comments, you
+can reach the author through the email address at the bottom of this
+page or via an RT ticket at
+L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
+
+
+
+=head2 Sorting Out Virtual Machine Network-Related Issues
+
+In general, using a virtual machine to work through the tutorial is
+*much* easier than trying to do it in other environments, especially if
+you are new to Catalyst (or Perl or CPAN or ...). However, it's
+possible that you could run into a few network-related issues. The good
+news is that there is lots of information about the issue available via
+search engines on the Internet. Here is some background information to
+get you started.
+
+In Step 5 of the prior section above, we assumed that a "Bridged Mode"
+configuration and DHCP will work (it should for most people). If DHCP
+is not working or is not available in your location, most virtual
+machine "host" environments let you select between one of several
+different types of networking between the "guest" and the "host"
+machine.
+
+ 1) Bridged
+ 2) NAT
+ 3) Local host only
+
+The Tutorial Virtual Machine defaults to "Bridged" -- this should result
+in the VM acting like another device on your network that will get a
+different DHCP IP address than the host machine. The advantage of this
+approach, is that you can easily SSH and web browse to the guest virtual
+machine. In general, this is the best option if you want to be able to
+boot up the VM and then use your SSH client and web browser from your
+main machine to connect into the virtual machine.
+
+In some environments, you might have better luck with "NAT" (Network
+Address Translation) mode. With this configuration, the guest VM shares
+the same IP address as the host machine. The downside of this approach
+is that special configuration is required if you want to be able to SSH
+or web browse to the guest VM. The NAT option should automatically
+allow the VM "outbound connection" (e.g., to the Internet if you want to
+install additional Debian packages), but it requires special
+configuration if you want to get "inbound connections" that go from some
+other machine (including the "host machine") into the VM. Some virtual
+machine host environments let you configure a "static NAT" or "port
+forwarding" to reach the guest OS, but others omit this functionality.
+
+Note: NAT mode can work fine if you install X Windows and do the whole
+tutorial locally on the actual VM vs. using SSH and a web browser from
+your host machine.
+
+"Local host only" mode let's the guest VM and the host machine talk on a
+"private subnet" that other devices in your network cannot reach. This
+can work as long as you don't need to go from the VM to the Internet
+(for example, to install other Debian packages).
+
+
+Consult the documentation on your virtual machine host environment for
+help configuring the options above. Here are some links that might
+help:
=over 4
=item *
-Debian
-
-The Debian 6 Live CD represents a great way for newcomers to experiment
-with Catalyst. As a "live CD," you can simple boot from the CD, run a
-few commands, and in a matter of minutes you should have a fully
-function environment in which do this tutorial. B<The tutorial was fully
-tested to work under Debian 6. Although it SHOULD work under any
-Catalyst installation method you might choose, it can be hard to
-guarantee this.>
-
-=over 4
-
-=item *
-
-Download one of the ISO files from
-L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/>
-(the current version at the time this was written was 6.0.1). You can
-pick any one of the live CD variations will work, but you may wish to
-consider the following points:
-
-=over 4
+L<http://vmfaq.com/entry/34/>
=item *
-"C<debian-live-6.0.1-i386-rescue.iso>" is probably the best all-around
-option for most people because it includes many extra tools such as the
-GCC compiler, therefore saving RAM (every package you need to install
-when running from a Live CD consumes memory because RAM disk is being
-used in lieu of real disk space). When initially booting under this
-image, you may see some cryptic warning messages having to do with
-various diagnostic tools it tries to load or enable, but you should be
-able to safely ignore these.
+L<http://www.vmware.com/support/pubs/player_pubs.html>
=item *
-"C<debian-live-6.0.1-i386-standard.iso>" is a great option because of
-its compact size, but you will probably need approximately 1 GB of RAM
-in the computer where you will run the tutorial. Because the "standard"
-live CD comes with with a minimal set of tools, we will have to install
-extra packages (such as the GCC compiler), all of which will require RAM
-when running from a live CD.
-
-=item *
-
-The other ISO images include different flavors of X-Windows desktop
-managers. You can select one of these if you don't mind the larger
-download size and prefer a graphical environment. Be aware that these
-disks do not come with the extra tools found on the "rescue" image, so
-you will need adequate RAM to be able to install them just as you would
-under the "standard" image. B<Use one of the "graphical" ISO images if
-you want a graphical web browser on the same machine as where you will
-run the tutorial.> (If you are using one of the non- graphical images
-discussed above, you can still use a graphical web browser from another
-machine and point it to your Catalyst development machine.)
+L<http://www.virtualbox.org/manual/ch06.html>
=back
-=item *
-Boot off the CD.
-=item *
-Select "C<Live>" from the initial boot menu.
-
-=item *
-
-Once the system has booted to a "C<user@debian:~$>" prompt, first
-install the Subversion client in case you want to check out the
-completed chapter example code:
-
- sudo aptitude -y install subversion
-
-If you want to be able to remotely SSH to this system, set a
-password for root:
-
- sudo passwd
- ...
-
-Then enter the following command to add the more current "unstable"
-package repository so we get the latest versions of Catalyst and related
-packages:
-
- sudo vi /etc/apt/sources.list
-
-Add the following line to the bottom of this file:
-
- deb http://ftp.us.debian.org/debian/ unstable main
-
-If you are not familiar with VI, you can move to the bottom of this file
-and press the "o" key to insert a new line and type the line above.
-Then press the "Esc" key followed by a colon (":"), the letters "wq" and
-then the "Enter" key. The rest of the tutorial will assume that you
-know how to use some editor that is available from the Linux
-command-line environment.
-
-=item *
-
-Install Catalyst:
-
- sudo aptitude update
- sudo aptitude -y install sqlite3 libdbd-sqlite3-perl libcatalyst-perl \
- libcatalyst-modules-perl libdbix-class-timestamp-perl \
- libdatetime-format-sqlite-perl libconfig-general-perl \
- libhtml-formfu-model-dbic-perl libterm-readline-perl-perl \
- libdbix-class-encodedcolumn-perl libperl6-junction-perl \
- libtest-pod-perl
-
-Let it install (normally about a 30 to 90-second operaton) and you are
-done. (Note the '\' above. Depending on your environment, you might
-be able to cut and paste the text as shown or need to remove the '\'
-characters to that the command is all on a single line.)
-
-If you are using an image other than the "rescue" ISO, you will also need
-to run the following command to install additional packages:
-
- sudo aptitude -y install gcc make libc6-dev
-
-If you are running from the Live CD, you probably also want to free up
-some RAM disk space with the following:
-
- sudo aptitude clean
-
-NOTE: While the instructions above mention the Live CD because that
-makes it easy for people new to Linux, you can obviously pick a
-different Debian ISO image and install it to your hard drive. Although
-there are many different ways to download and install Debian, the
-"netinst" ISO image (such as "C<debian-500-i386-netinst.iso>" represents
-a great option because it keeps your initial download small (but still
-lets you install anything you want "over the network").
+=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
-Here are some tips if you are running from a live CD and are running
-out of disk space (which really means you are running out of RAM):
+This tutorial was built using the following resources. Please note that
+you may need to make adjustments for different environments and versions
+(note that trailing zeros in version numbers are not significant and may
+get dropped with some techniques for viewing them; for example, Catalyst
+v5.80020 might show up as 5.8002):
=over 4
-=item *
-
-Always run "C<aptitude clean>" after you install new packages to delete
-the original .deb files (the files installed B<by> the .deb package
-B<will> remain available, just the .deb package itself is deleted).
-
-=item *
-
-If you are installing modules from CPAN, you can free up some space with
-"C<rm -rf /root/.cpan/*>" (change "/root/" in the previous command to
-match your home directory or the location where CPAN has been configured
-to perform build operations).
-
-=item *
-
-If necessary, you can remove the cached package information with the
-command "C<rm -f /var/lib/apt/lists/*>". You can later pull this
-information again via the command "C<aptitude update>".
-
=item *
-You can save a small amount of space by commenting out the lines in
-C</etc/apt/sources.list> that reference "deb-src" and
-"security.debian.org". If you have already done an "C<aptitude update>"
-with these repositories enabled, you can use the tip in the previous
-bullet to free the space up (and then do another "C<aptitude update>").
-
-=item *
-
-Although you can free up space by removing packages you installed since
-you last booted (check out "C<aptitude remove _pkg_name_>"), don't bother
-trying to remove packages already available at the time of boot. Instead
-of freeing up space, it will actual consume I<more> space. (The live CD
-uses these "burn in" packages right from the CD disk vs. first loading
-them on the virtual RAM disk. However, if you remove them, the system
-has to update various files, something that I<does> consume some space
-on the virtual RAM disk.)
+Debian 6 (Squeeze)
-=back
+=item *
-=back
+Catalyst v5.90002
=item *
-Ubuntu
-
-Ubuntu is a popular offshoot of Debian. It provides cutting edge
-versions of many common tools, application and libraries in an
-easy-to-run live CD configuration (and because a single download option
-can be used for both live CD and install-to-disk usage, it keeps your
-download options nice and simple). As with Debian 6, you should be able
-to generate a fully function Catalyst environment in a matter of
-minutes. Here are quick instructions on how to use Ubuntu to prepare
-for the tutorial:
-
-=over 4
+Catalyst::Devel v1.34
=item *
-Download the Ubuntu Desktop edition and boot from the CD and/or image
-file, select your language, and then "Try Ubuntu without any changes to
-your computer."
+DBIx::Class v0.08195
=item *
-Open a terminal session (click "Applications" in the upper-left corner,
-then "Accessories," then "Terminal").
+Catalyst::Model::DBIC::Schema v0.54
=item *
-Add the 'universe' repositories:
+Template Toolkit v2.22
- sudo gedit /etc/apt/sources.list
-
-And remove the comments from the lines under the comments about the
-'universe' repositories.
=item *
-Install Catalyst:
-
- sudo aptitude update
- sudo aptitude install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl libconfig-general-perl
-
-Accept all of the dependencies. Done.
-
-If you are running from the Live CD, you probably also want to free up
-some disk space with the following:
-
- sudo aptitude clean
-
-NOTE: While the instructions above mention the live CD because that
-makes it easy for people new to Linux, you can obviously also use one of
-the options to install Ubuntu on your drive.
-
-=back
+HTML::FormFu -- v0.09004
=item *
-Matt Trout's C<cat-install>
-
-Available at L<http://www.shadowcat.co.uk/static/cat-install>,
-C<cat-install> can be a fairly painless way to get Catalyst up and
-running. Just download the script from the link above and type
-C<perl cat-install>. Depending on the speed of your Internet connection
-and your computer, it will probably take 30 to 60 minutes to install
-because it downloads, makes, compiles, and tests every module. But this
-is an excellent way to automate the installation of all the latest
-modules used by Catalyst from CPAN.
-
-
-=item *
-
-Other Possibilities
-
-=over 4
-
-=item *
-
-OpenBSD Packages
+B<NOTE:> You can check the versions you have installed with the
+following command (note the slash before the space):
-The 2008 Advent Day 4 entry has more information on using OpenBSD
-packages to quickly build a system:
-L<http://www.catalystframework.org/calendar/2008/4>.
+ perl -M<_mod_name_>\ 999
-=item *
+or:
-NetBSD Package Collection on Solaris
+ perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
-The 2008 Advent Day 15 entry has more information on using C<pkgsrc> and
-NetBSD packages on Solaris:
-L<http://www.catalystframework.org/calendar/2008/15>.
+For example:
-=item *
+ perl -MCatalyst::Devel\ 999
-CatInABox
+or:
-You can get more information at
-L<http://www.catalystframework.org/calendar/2008/7> or
-L<Perl::Dist::CatInABox|Perl::Dist::CatInABox>.
+ perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
=item *
-Frank Speiser's Amazon EC2 Catalyst SDK
-
-There are currently two flavors of publicly available Amazon Machine
-Images (AMI) that include all the elements you'd need to begin
-developing in a fully functional Catalyst environment within minutes.
-See L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>
-for more details.
+This tutorial will show URLs in the format of C<http://localhost:3000>,
+but if you are running your web browser from outside the Tutorial
+Virtual Machine, you will want to substitute the IP address of your VM
+for the C<localhost> in the URLs (again, you can get the IP address for
+eth0 from the C<ifconfig> command). For example, if your VM has an
+IP address of 192.168.0.12, you will want to use a base URL of
+C<http://192.168.0.12:3000>. Note that the development server
+defaults to port 3000 (you can change with with the "-p" option on the
+command line.
+
+B<Please Note:> Depending on the web browser you are using, you might
+need to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
+testing your application at various points (see
+L<http://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache> for a
+comprehensive list of options for each browser).
-=back
+Also, the C<-k> B<keepalive option> to the development server can be
+necessary with some browsers (B<especially Internet Explorer>).
=back
-For additional information and recommendations on Catalyst installation,
-please refer to
-L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>.
-
=head1 DATABASES
same.
-=head1 WHERE TO GET WORKING CODE
-
-Each chapter of the tutorial has complete code available as a tarball in
-the main Catalyst Subversion repository (see the note at the beginning
-of each part for the appropriate svn command to use).
-
-B<NOTE:> You can run the test cases for the final code through Chapter 8
-with the following commands:
-
- svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8
- cd MyApp_Chapter8/MyApp
- CATALYST_DEBUG=0 prove -wl t
-
-If you wish to include the L<HTML::FormFu|HTML::FormFu> section in your tests,
-substitute C<MyApp_Chapter9_FormFu> for C<MyApp_Chapter8> in the URL
-above (don't forget to "cd" out of the Ch8 directory if you ran the code above).
-
- svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter9_FormFu
- cd MyApp_Chapter9_FormFu/MyApp
- CATALYST_DEBUG=0 prove -wl t
-
-You can also fire up the application under the development server that is conveniently
-built in to Catalyst. Just issue this command from the C<MyApp> directory where you
-ran the test suite above:
-
- script/myapp_server.pl
-
-And the application will start. You can try out the application by
-pulling up C<http://localhost:3000> in your web browser (as mentioned
-earlier, change C<localhost> to a different IP address or DNS name if
-you are running your web browser and your Catalyst development on
-different boxes). We will obviously see more about how to use the
-application as we go through the remaining chapters of the tutorial, but
-for now you can log in using the username "test01" and a password of
-"mypass".
+You can jump to the next chapter of the tutorial here:
+L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
=head1 AUTHOR
Kennedy Clark, C<hkclark@gmail.com>
-Please report any errors, issues or suggestions to the author. The
-most recent version of the Catalyst Tutorial can be found at
-L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
+Feel free to contact the author for any errors or suggestions, but the
+best way to report issues is via the CPAN RT Bug system at
+L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
-Copyright 2006-2010, Kennedy Clark, under the
+Copyright 2006-2011, Kennedy Clark, under the
Creative Commons Attribution Share-Alike License Version 3.0
(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).
projects / catagits/Catalyst-Manual.git / blobdiff