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=9b5062249107e32cbefd0da74b32f1720f749351;hp=d7b6ad41d52ab32cc237d1621879e1731f40ef74;hb=11bd76471beca4e0f685d5f2de288796e7ea23dd;hpb=24acc5d75bb4208eeef4d1bad0974f0fd5893454 diff --git a/lib/Catalyst/Manual/Tutorial/01_Intro.pod b/lib/Catalyst/Manual/Tutorial/01_Intro.pod index d7b6ad4..9b50622 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 for you 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 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 @@ -400,10 +574,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).