X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2F01_Intro.pod;h=8419f7601710031fc840c08b180ee1529339339c;hb=69d57cda557b2f9a04a058dfd4e875c1d9153133;hp=40d715d4a380d3ce6e1938116611ef6b89a655ec;hpb=232da04a3754fcc56a885c4cce6338a65c799989;p=catagits%2FCatalyst-Manual.git
diff --git a/lib/Catalyst/Manual/Tutorial/01_Intro.pod b/lib/Catalyst/Manual/Tutorial/01_Intro.pod
index 40d715d..8419f76 100644
--- a/lib/Catalyst/Manual/Tutorial/01_Intro.pod
+++ b/lib/Catalyst/Manual/Tutorial/01_Intro.pod
@@ -70,21 +70,29 @@ form management).
The most recent code for the tutorial is included on the Tutorial Virtual
Machine you can download from:
+L
+
+See L 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
+errors, or accidentally skipped part of the tutorial.
B It should make little or no difference to Catalyst's
operation, B that you can download and use to work through
the full tutorial step by step. B to avoid issues
that may crop up if you are working with a different configuration. We
@@ -176,24 +184,38 @@ applications can be found at
L and
in the C area of the Catalyst Subversion repository at
L.
-***Todo: update link above?
-
=head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE
+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 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" (where "C<~"> will change to show your
+current directory), but we will keep it short and just use "C<$>".
+
+
=over 4
=item 1
-Download the C image from
-L.
+Download a Tutorial Virtual Machine image from
+L
+
+B
+B<(and everything else they do for the Perl community)!>
=item 2
-Uncompress the image:
+Uncompress the image on the "host machine":
- tar zxvf CatalystTutorial.tgz
+ MAINCOMPUTER:~$ tar zxvf CatalystTutorial.tgz
=item 3
@@ -203,12 +225,14 @@ L.
=item 4
-Once you get a login prompt, enter the username B and a password
-for C. You should now be at a prompt that looks like:
+Once you get a login prompt, enter the username B and a
+password for C. You should now be at a prompt that looks
+like:
- login: root
- password: catalyst
- root@catalyst:~#
+ catalyst login: catalyst
+ Password: catalyst
+ ...
+ catalyst@catalyst:~$
=item 5
@@ -216,47 +240,51 @@ Type "C" to get the IP address assigned to the virtual
machine. You should get output along the lines of:
eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69
- inet addr:192.168.245.128 Bcast:192.168.245.255 Mask:255.255.255.0
+ inet addr:192.168.0.12 Bcast:192.168.0.255 Mask:255.255.255.0
...
You want the IP address on the second line below the C interface.
The image it design to automatically use a DHCP-assigned address.
-If DHCP is not working or is not available in your location, most
-virtual machine "host" environments let's 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
+Try to ping this IP address from your "host machine" (main desktop):
-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 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 the approach
-is that special configuration is required if you want to be able to SSH
-or web browse to the guest VM (some virtual machine host environments
-let you configure a "static NAT" or "port forwarding" to reach the guest
-OS).
+ 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
+ ...
-"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.
-Consult the documentation on your virtual machine host environment for
-help configuring the options above.
+B The ping above is being originated B your B
+(main desktop) and going B your guest B, not the
+other way around.
+
+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
+for additional information and troubleshooting advice.
+
+B Remember this IP address... you will be using it throughout the
+tutorial.
+
=item 6
-B, 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). Login with the same username and password:
-B / B
+B, 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 /
+B
+
+ catalyst login: catalyst
+ Password: catalyst
+ ...
+ catalyst@catalyst:~$
+
=item 7
@@ -264,18 +292,18 @@ B, change to the sample code directory for
Chapter 3 included with the Tutorial Virtual Machine and start the
Catalyst Development Server:
- $ cd Final/Chapter03
- $ perl scripts/myapp_server -r
+ $ cd Final/Chapter03/MyApp
+ $ perl script/myapp_server.pl
=item 8
-B, open a web browser and go to
-B, where C 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.21>, you would put
-the following URL into your web browser:
+B (the "host machine"), open a web
+browser and go to B, where C 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:
- http://192.168.0.21:3000/
+ http://192.168.0.12:3000/
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.
@@ -287,17 +315,162 @@ back and carefully check each of the steps above.
=item 9
-B 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, :-) Debian fortunately make it very easy to
-install Emacs:
+B 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 package manager to install other packages.
+You will first want to pull the apt cache files with C
+(or C if you prefer apt-get).
+
+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:
+
+ $ sudo aptitude update
+ $ sudo aptitude install emacs
+
+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 (or C) Debian commands.
+
+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:
+
+ $ sudo aptitude update
+ $ sudo aptitude install xorg fluxbox iceweasel
+
+And then start X Windows from the B with this command:
+
+ $ startx
+
+Note that if you want to start Fluxbox from an SSH session, you can use
+the C and select "anybody" from the
+menu. Otherwise, you will need to be on the actual "VM console" to
+start it.
+
+If you have a preference for the Gnome desktop environment, you can do:
+
+ $ sudo aptitude update
+ $ sudo aptitude install gnome iceweasel
+ $
+ $ # You can reboot or start with 'startx', we will just reboot here
+ $ reboot
+
+For KDE, just substitute the package name "C" for "C" above.
+
+ $ sudo aptitude install kde iceweasel
+
+Note that C is basically used to install Firefox on Debian
+boxes. You can start it under X Windows with either the C
+command or the C command (or use the menus). You can get
+more information on Iceweasel at L.
+
+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 of your virtualization software
+for instructions on how to do this (it's usually pretty simple).
+
- $ aptitude install emacs
+=back
+
+
+You may note that the Tutorial Virtual Machine uses L 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 run
+both the modules B Perl itself from your home directory [or any
+other directory you chose]).
+
+B: 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.
+
+
+
+=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 *
+
+L
+
+=item *
+
+L
+
+=item *
+
+L
=back
+
+
=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
This tutorial was built using the following resources. Please note that
@@ -363,18 +536,19 @@ 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 in the URLs (again, you can get the IP address for
eth0 from the C command). For example, if your VM has an
-IP address of 192.168.245.128, you will want to use a base URL of
-C. Note that the development server
+IP address of 192.168.0.12, you will want to use a base URL of
+C. Note that the development server
defaults to port 3000 (you can change with with the "-p" option on the
command line.
-B Depending on the web browser you are using, you might need
-to hit C or C to pull a fresh page when
+B Depending on the web browser you are using, you might
+need to hit C or C to pull a fresh page when
testing your application at various points (see
-L 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).
+L for a
+comprehensive list of options for each browser).
+
+Also, the C<-k> B to the development server can be
+necessary with some browsers (B).
=back
@@ -392,14 +566,18 @@ change between database systems: most of the code generally remains the
same.
+You can jump to the next chapter of the tutorial here:
+L
+
+
=head1 AUTHOR
Kennedy Clark, C
-Please report any errors, issues or suggestions to the author. The
-most recent version of the Catalyst Tutorial can be found at
-L.
+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.
-Copyright 2006-2010, Kennedy Clark, under the
+Copyright 2006-2011, Kennedy Clark, under the
Creative Commons Attribution Share-Alike License Version 3.0
(L).