X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2F01_Intro.pod;h=297e0b91dda13def394456c7542d054fce77d9cc;hp=12278374e1841a513408dac43a35fb285e7c8dc4;hb=d35624c1e68939a527c25ff751c312ed3235594f;hpb=3f97ca7b9f6e5ac8c83e3c51cfd4985d95fa64b9 diff --git a/lib/Catalyst/Manual/Tutorial/01_Intro.pod b/lib/Catalyst/Manual/Tutorial/01_Intro.pod index 1227837..297e0b9 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,18 +184,35 @@ 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". + +Also, to reduce download size, the Tutorial VM just includes a minimal +command-line environment. 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. + + =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 @@ -217,47 +242,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: root + Password: catalyst + ... + root@catalyst:~# + =item 7 @@ -265,18 +294,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 scripts/myapp_server =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. @@ -299,6 +328,93 @@ 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, /root/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 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. + +"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 @@ -364,18 +480,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 @@ -401,10 +518,10 @@ L 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).