Commit | Line | Data |
d442cc9f |
1 | =head1 NAME |
2 | |
3ab6187c |
3 | Catalyst::Manual::Tutorial::01_Intro - Catalyst Tutorial - Chapter 1: Introduction |
d442cc9f |
4 | |
5 | |
6 | =head1 OVERVIEW |
7 | |
4b4d3884 |
8 | This is B<Chapter 1 of 10> for the Catalyst tutorial. |
d442cc9f |
9 | |
10 | L<Tutorial Overview|Catalyst::Manual::Tutorial> |
11 | |
12 | =over 4 |
13 | |
14 | =item 1 |
15 | |
3ab6187c |
16 | B<01_Introduction> |
d442cc9f |
17 | |
18 | =item 2 |
19 | |
3ab6187c |
20 | L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics> |
d442cc9f |
21 | |
22 | =item 3 |
23 | |
3ab6187c |
24 | L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics> |
d442cc9f |
25 | |
26 | =item 4 |
27 | |
3ab6187c |
28 | L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD> |
d442cc9f |
29 | |
30 | =item 5 |
31 | |
3ab6187c |
32 | L<Authentication|Catalyst::Manual::Tutorial::05_Authentication> |
d442cc9f |
33 | |
34 | =item 6 |
35 | |
3ab6187c |
36 | L<Authorization|Catalyst::Manual::Tutorial::06_Authorization> |
d442cc9f |
37 | |
38 | =item 7 |
39 | |
3ab6187c |
40 | L<Debugging|Catalyst::Manual::Tutorial::07_Debugging> |
d442cc9f |
41 | |
42 | =item 8 |
43 | |
3ab6187c |
44 | L<Testing|Catalyst::Manual::Tutorial::08_Testing> |
d442cc9f |
45 | |
46 | =item 9 |
47 | |
3ab6187c |
48 | L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD> |
1def4a20 |
49 | |
50 | =item 10 |
51 | |
3ab6187c |
52 | L<Appendices|Catalyst::Manual::Tutorial::10_Appendices> |
d442cc9f |
53 | |
54 | =back |
55 | |
1def4a20 |
56 | |
d442cc9f |
57 | =head1 DESCRIPTION |
58 | |
ffeb7448 |
59 | This tutorial provides a multi-part introduction to the Catalyst web |
d442cc9f |
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. |
63 | |
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 |
1def4a20 |
66 | example, how to use DBIC for their model classes, how to add |
8168726b |
67 | authentication and authorization to an existing application, and/or |
68 | form management). |
d442cc9f |
69 | |
70 | You can obtain the code for all the tutorial examples from the |
71 | catalyst subversion repository by issuing the command: |
72 | |
028b4e1a |
73 | svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial |
d442cc9f |
74 | |
75b13da6 |
75 | This will download the most recent code for each chapter of the |
76 | tutorial into the CatalystTutorial directory on your machine. |
d442cc9f |
77 | |
3d9ae335 |
78 | B<These reference implementations are provided so that when you follow |
79 | the tutorial, you can use the code from the subversion repository to |
80 | ensure that your system is set up correctly, and that you have not |
81 | inadvertently made any typographic errors, or accidentally skipped |
82 | part of the tutorial.> |
83 | |
8168726b |
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 |
a6b4cff5 |
86 | operation, B<but this tutorial has been written using the Debian 6 Live |
8168726b |
87 | CD> because that represents a quick and easy way for most people to try |
88 | out Catalyst with virtually zero setup time and hassles. Also, the |
89 | tutorial has been tested to work correctly with the versions of Catalyst |
90 | and all the supporting modules in Debian 6 (see "VERSIONS AND |
91 | CONVENTIONS USED IN THIS TUTORIAL" below for the specific versions for |
92 | some of the key modules), so B<if you think you might be running into an |
93 | issue related to versions> (for example, a module changed its behavior |
94 | in a newer version or a bug was introduced), B<it might be worth giving |
95 | Debian 6 a try>. |
96 | |
97 | If you plan to follow along with Debian 6, you can jump down to the |
98 | "Debian" section under L</"CATALYST INSTALLATION"> below and it will |
99 | walk you though the setup of a fully functional Catalyst environment. If |
100 | you would prefer to install directly from CPAN, you can download the |
101 | example program and all the necessary dependencies to your local machine |
102 | by installing the C<Task::Catalyst::Tutorial> distribution: |
d442cc9f |
103 | |
104 | cpan Task::Catalyst::Tutorial |
105 | |
106 | This will also test to make sure the dependencies are working. If you |
107 | have trouble installing these, please ask for help on the #catalyst |
108 | IRC channel, or the Catalyst mailing list. |
109 | |
3533daff |
110 | Subjects covered by the tutorial include: |
d442cc9f |
111 | |
112 | =over 4 |
113 | |
114 | =item * |
115 | |
116 | A simple application that lists and adds books. |
117 | |
118 | =item * |
119 | |
8168726b |
120 | The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model (including |
121 | some of the more advanced techniques you will probably want to use in |
acbd7bdd |
122 | your applications). |
d442cc9f |
123 | |
124 | =item * |
125 | |
126 | How to write CRUD (Create, Read, Update, and Delete) operations in |
127 | Catalyst. |
128 | |
129 | =item * |
130 | |
131 | Authentication ("auth"). |
132 | |
133 | =item * |
134 | |
135 | Role-based authorization ("authz"). |
136 | |
137 | =item * |
138 | |
8168726b |
139 | Attempts to provide an example showing current (5.9) Catalyst |
140 | practices. |
d442cc9f |
141 | |
142 | =item * |
143 | |
1390ef0e |
144 | The use of Template Toolkit (TT). |
d442cc9f |
145 | |
146 | =item * |
147 | |
148 | Useful techniques for troubleshooting and debugging Catalyst |
149 | applications. |
150 | |
151 | =item * |
152 | |
153 | The use of SQLite as a database (with code also provided for MySQL and |
8168726b |
154 | PostgreSQL). (Note: Because we make use of the DBIx::Class Object |
444d6b27 |
155 | Relational Mapping [ORM] layer, out our application will be database |
8168726b |
156 | agnostic and can easily be used by any of the databases supported by |
157 | DBIx::Class.) |
d442cc9f |
158 | |
159 | =item * |
160 | |
0abc72ed |
161 | The use of L<HTML::FormFu|HTML::FormFu> or L<HTML::FormHandler|HTML::FormHandler> |
162 | for automated form processing and validation. |
d442cc9f |
163 | |
164 | =back |
165 | |
166 | This tutorial makes the learning process its main priority. For |
167 | example, the level of comments in the code found here would likely be |
1def4a20 |
168 | considered excessive in a "normal project." Because of their contextual |
d442cc9f |
169 | value, this tutorial will generally favor inline comments over a |
170 | separate discussion in the text. It also deliberately tries to |
171 | demonstrate multiple approaches to various features (in general, you |
172 | should try to be as consistent as possible with your own production |
173 | code). |
174 | |
175 | Furthermore, this tutorial tries to minimize the number of controllers, |
176 | models, TT templates, and database tables. Although this does result in |
177 | things being a bit contrived at times, the concepts should be applicable |
178 | to more complex environments. More complete and complicated example |
179 | applications can be found in the C<examples> area of the Catalyst |
180 | Subversion repository at |
181 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>. |
8168726b |
182 | ***Todo: update link above? |
d442cc9f |
183 | |
1390ef0e |
184 | |
2e73e2be |
185 | =head1 QUICK START |
186 | |
8168726b |
187 | For those who want to get going quickly, here is a short "cookbook-style |
188 | recipe" to quickly get you up and running. Although there are many |
189 | different ways to get a Catalyst environment going, this tutorial has |
a6b4cff5 |
190 | been written with and tested against the Debian 6 Live CD, using the |
191 | steps in this Quick Start. |
2e73e2be |
192 | |
8168726b |
193 | If you want, you can follow the directions in this section and then jump |
194 | right to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics> of |
195 | the tutorial. However, it would be a good idea to come back and read the |
196 | sections below the Quick Start when you have time. Or, continue reading |
197 | those other sections for suggestions if you do not wish to use the |
198 | Debian 6 Live CD. |
2e73e2be |
199 | |
2e73e2be |
200 | =over 4 |
201 | |
202 | =item 1 |
203 | |
8168726b |
204 | Download the C<debian-live-6.0.1-i386-rescue.iso> image from |
205 | L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/>. |
2e73e2be |
206 | |
207 | =item 2 |
208 | |
209 | Boot this disk, either in a physical machine, or possibly some sort |
8168726b |
210 | of virtual machine (using a VM can be a very handy way to practice). |
2e73e2be |
211 | |
212 | =item 3 |
213 | |
214 | Select "C<Live>" from the initial boot menu. |
215 | |
216 | =item 4 |
217 | |
218 | At the "C<user@debian:~$>" prompt, type: |
219 | |
220 | sudo aptitude -y install subversion |
221 | |
222 | =item 5 |
223 | |
224 | If you want to be able to remotely SSH to this system, set a |
a6b4cff5 |
225 | password for root (you might want to do "dpkg -l | grep openssh-server" |
226 | to be sure the ISO image you downloaded has the SSH daemon installed... |
227 | if it's missing, do a "sudo aptitude -y install openssh-server"): |
2e73e2be |
228 | |
229 | sudo passwd |
230 | ... |
231 | |
232 | =item 6 |
233 | |
234 | Add the "unstable" Debian package repository: |
235 | |
236 | sudo vi /etc/apt/sources.list |
237 | |
238 | Add the following line to the bottom of this file: |
239 | |
240 | deb http://ftp.us.debian.org/debian/ unstable main |
241 | |
242 | =item 7 |
243 | |
244 | Install Catalyst and related libraries: |
245 | |
246 | sudo aptitude update |
a5628822 |
247 | sudo aptitude -y install libcatalyst-perl libdatetime-format-sqlite-perl \ |
248 | libdbix-class-encodedcolumn-perl sqlite3 libcatalyst-modules-perl \ |
249 | libperl6-junction-perl libcatalyst-modules-extra-perl \ |
250 | libdbix-class-timestamp-perl |
2e73e2be |
251 | sudo aptitude clean |
252 | |
253 | =item 8 |
254 | |
255 | Test example code: |
256 | |
257 | mkdir test |
258 | cd test |
259 | svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8 |
260 | cd MyApp_Chapter8/MyApp |
261 | CATALYST_DEBUG=0 prove -wl t |
262 | cd |
263 | |
264 | =back |
265 | |
266 | |
d442cc9f |
267 | =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL |
268 | |
269 | This tutorial was built using the following resources. Please note that |
a6b4cff5 |
270 | you may need to make adjustments for different environments and versions |
271 | (note that trailing zeros in version numbers are not significant and may |
272 | get dropped with some techniques for viewing them; for example, Catalyst |
273 | v5.80020 might show up as 5.8002): |
d442cc9f |
274 | |
275 | =over 4 |
276 | |
277 | =item * |
278 | |
acbd7bdd |
279 | Debian 5 (Lenny) |
d442cc9f |
280 | |
281 | =item * |
282 | |
6163536a |
283 | Catalyst v5.80020 (note: may show up as '5.8002' without the trailing zero) |
dd88c3b6 |
284 | |
22a67212 |
285 | =item * |
dd88c3b6 |
286 | |
6163536a |
287 | Catalyst::Devel v1.26 |
d442cc9f |
288 | |
289 | =item * |
290 | |
6163536a |
291 | DBIx::Class v0.08115 |
d442cc9f |
292 | |
fce83e5f |
293 | =item * |
294 | |
2e73e2be |
295 | Catalyst::Model::DBIC::Schema v0.40 |
296 | |
297 | =item * |
298 | |
fce83e5f |
299 | Template Toolkit v2.20 |
300 | |
2e73e2be |
301 | |
d442cc9f |
302 | =item * |
303 | |
304 | Catalyst Plugins |
305 | |
306 | The plugins used in this tutorial all have sufficiently stable APIs that |
307 | you shouldn't need to worry about versions. However, there could be |
308 | cases where the tutorial is affected by what version of plugins you |
309 | use. This tutorial has been tested against the following set of plugins: |
310 | |
311 | =over 4 |
312 | |
313 | =item * |
314 | |
6163536a |
315 | Catalyst::Plugin::Authentication -- v0.10016 |
d442cc9f |
316 | |
317 | =item * |
318 | |
6163536a |
319 | Catalyst::Plugin::Authorization::Roles -- v0.08 |
d442cc9f |
320 | |
321 | =item * |
322 | |
f34d7f62 |
323 | Catalyst::Plugin::ConfigLoader -- v0.27 |
d442cc9f |
324 | |
325 | =item * |
326 | |
f34d7f62 |
327 | Catalyst::Plugin::Session -- v0.29 |
d442cc9f |
328 | |
329 | =item * |
330 | |
f34d7f62 |
331 | Catalyst::Plugin::Session::State::Cookie -- v0.17 |
d442cc9f |
332 | |
333 | =item * |
334 | |
95455c74 |
335 | Catalyst::Plugin::Session::Store::File -- v0.18 |
d442cc9f |
336 | |
337 | =item * |
338 | |
f34d7f62 |
339 | Catalyst::Plugin::StackTrace -- v0.11 |
d442cc9f |
340 | |
341 | =item * |
342 | |
2e73e2be |
343 | Catalyst::Plugin::Static::Simple -- v0.29 |
d442cc9f |
344 | |
345 | =back |
346 | |
2e73e2be |
347 | =item * |
348 | |
349 | HTML::FormFu -- v0.06001 |
350 | |
d442cc9f |
351 | =item * |
352 | |
865d3efb |
353 | B<NOTE:> You can check the versions you have installed with the |
354 | following command: |
355 | |
f63a9a2b |
356 | perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"' |
865d3efb |
357 | |
358 | For example: |
865d3efb |
359 | |
444d6b27 |
360 | perl -MCatalyst -e 'print "$Catalyst::VERSION\n";' |
361 | |
362 | or: |
363 | |
364 | perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";' |
d442cc9f |
365 | |
366 | =item * |
367 | |
8168726b |
368 | This tutorial will assume that the web browser is located on the same |
369 | system where the Catalyst development server is running, and therefore |
370 | use a URL of C<http://localhost:3000> (the Catalyst development server |
a6b4cff5 |
371 | defaults to port 3000, but can be changed with the "-p" option to the |
372 | development server). If you are running Perl on a different box than |
8168726b |
373 | where your web browser is located (or using a different port number via |
374 | the C<-p> I<port_number> option to the development server), then you |
375 | will need to update the URL you use accordingly. |
376 | |
377 | Please Note: Depending on the web browser you are using, you might need |
378 | to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when |
379 | testing your application at various points (see |
380 | L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive |
381 | list of options for each browser). Also, the C<-k> keepalive option to |
382 | the development server can be necessary with some browsers (especially |
383 | Internet Explorer). ***Todo: is this still true? |
d442cc9f |
384 | |
385 | =back |
386 | |
1390ef0e |
387 | |
d442cc9f |
388 | =head1 CATALYST INSTALLATION |
389 | |
8168726b |
390 | Although Catalyst installation has been a challenge in the past, the |
391 | good news is that there are a growing number of options to eliminate (or |
392 | at least dramatically simplify) this concern. Although a compelling |
393 | strength of Catalyst is that it makes use of many of the modules in the |
394 | vast repository that is CPAN, this can complicate the installation |
395 | process if you approach it in the wrong way. Consider the following |
396 | suggestions on the most common ways to get started with a Catalyst |
397 | development environment: |
1def4a20 |
398 | |
399 | =over 4 |
400 | |
401 | =item * |
402 | |
acbd7bdd |
403 | Debian |
404 | |
8168726b |
405 | The Debian 6 Live CD represents a great way for newcomers to experiment |
406 | with Catalyst. As a "live CD," you can simple boot from the CD, run a |
407 | few commands, and in a matter of minutes you should have a fully |
408 | function environment in which do this tutorial. B<The tutorial was fully |
409 | tested to work under Debian 6. Although it SHOULD work under any |
410 | Catalyst installation method you might choose, it can be hard to |
411 | guarantee this.> |
acbd7bdd |
412 | |
413 | =over 4 |
414 | |
415 | =item * |
416 | |
8168726b |
417 | Download one of the ISO files from |
418 | L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/> |
419 | (the current version at the time this was written was 6.0.1). You can |
420 | pick any one of the live CD variations will work, but you may wish to |
421 | consider the following points: |
acbd7bdd |
422 | |
423 | =over 4 |
424 | |
425 | =item * |
426 | |
8168726b |
427 | "C<debian-live-6.0.1-i386-rescue.iso>" is probably the best all-around |
428 | option for most people because it includes many extra tools such as the |
429 | GCC compiler, therefore saving RAM (every package you need to install |
a6b4cff5 |
430 | when running from a Live CD consumes memory because RAM disk is being |
431 | used in lieu of real disk space). When initially booting under this |
432 | image, you may see some cryptic warning messages having to do with |
433 | various diagnostic tools it tries to load or enable, but you should be |
434 | able to safely ignore these. |
acbd7bdd |
435 | |
436 | =item * |
437 | |
8168726b |
438 | "C<debian-live-6.0.1-i386-standard.iso>" is a great option because of |
439 | its compact size, but you will probably need approximately 1 GB of RAM |
440 | in the computer where you will run the tutorial. Because the "standard" |
441 | live CD comes with with a minimal set of tools, we will have to install |
442 | extra packages (such as the GCC compiler), all of which will require RAM |
443 | when running from a live CD. |
acbd7bdd |
444 | |
445 | =item * |
446 | |
8168726b |
447 | The other ISO images include different flavors of X-Windows desktop |
448 | managers. You can select one of these if you don't mind the larger |
449 | download size and prefer a graphical environment. Be aware that these |
450 | disks do not come with the extra tools found on the "rescue" image, so |
451 | you will need adequate RAM to be able to install them just as you would |
452 | under the "standard" image. B<Use one of the "graphical" ISO images if |
453 | you want a graphical web browser on the same machine as where you will |
454 | run the tutorial.> (If you are using one of the non- graphical images |
455 | discussed above, you can still use a graphical web browser from another |
456 | machine and point it to your Catalyst development machine.) |
acbd7bdd |
457 | |
458 | =back |
459 | |
460 | =item * |
461 | |
462 | Boot off the CD. |
463 | |
464 | =item * |
465 | |
466 | Select "C<Live>" from the initial boot menu. |
467 | |
468 | =item * |
469 | |
6163536a |
470 | Once the system has booted to a "C<user@debian:~$>" prompt, first |
471 | install the Subversion client in case you want to check out the |
472 | completed chapter example code: |
473 | |
0ed3df53 |
474 | sudo aptitude -y install subversion |
6163536a |
475 | |
2e73e2be |
476 | If you want to be able to remotely SSH to this system, set a |
477 | password for root: |
478 | |
479 | sudo passwd |
480 | ... |
481 | |
8168726b |
482 | Then enter the following command to add the more current "unstable" |
483 | package repository so we get the latest versions of Catalyst and related |
484 | packages: |
acbd7bdd |
485 | |
486 | sudo vi /etc/apt/sources.list |
487 | |
488 | Add the following line to the bottom of this file: |
489 | |
490 | deb http://ftp.us.debian.org/debian/ unstable main |
491 | |
8168726b |
492 | If you are not familiar with VI, you can move to the bottom of this file |
493 | and press the "o" key to insert a new line and type the line above. |
494 | Then press the "Esc" key followed by a colon (":"), the letters "wq" and |
495 | then the "Enter" key. The rest of the tutorial will assume that you |
496 | know how to use some editor that is available from the Linux |
497 | command-line environment. |
acbd7bdd |
498 | |
499 | =item * |
500 | |
501 | Install Catalyst: |
502 | |
503 | sudo aptitude update |
a5628822 |
504 | sudo aptitude -y install libcatalyst-perl libdatetime-format-sqlite-perl \ |
505 | libdbix-class-encodedcolumn-perl sqlite3 libcatalyst-modules-perl \ |
506 | libperl6-junction-perl libcatalyst-modules-extra-perl \ |
507 | libdbix-class-timestamp-perl |
508 | |
509 | Let it install (normally about a 30 to 90-second operation) and you are |
510 | done. (Note the '\' above. Depending on your environment, you might be |
511 | able to cut and paste the text as shown or need to remove the '\' |
fce83e5f |
512 | characters to that the command is all on a single line.) |
acbd7bdd |
513 | |
514 | If you are using an image other than the "rescue" ISO, you will also need |
515 | to run the following command to install additional packages: |
516 | |
517 | sudo aptitude -y install gcc make libc6-dev |
518 | |
8168726b |
519 | If you are running from the Live CD, you probably also want to free up |
acbd7bdd |
520 | some RAM disk space with the following: |
521 | |
522 | sudo aptitude clean |
523 | |
8168726b |
524 | NOTE: While the instructions above mention the Live CD because that |
525 | makes it easy for people new to Linux, you can obviously pick a |
526 | different Debian ISO image and install it to your hard drive. Although |
527 | there are many different ways to download and install Debian, the |
528 | "netinst" ISO image (such as "C<debian-500-i386-netinst.iso>" represents |
529 | a great option because it keeps your initial download small (but still |
530 | lets you install anything you want "over the network"). |
acbd7bdd |
531 | |
532 | Here are some tips if you are running from a live CD and are running |
533 | out of disk space (which really means you are running out of RAM): |
534 | |
535 | =over 4 |
536 | |
537 | =item * |
538 | |
8168726b |
539 | Always run "C<aptitude clean>" after you install new packages to delete |
540 | the original .deb files (the files installed B<by> the .deb package |
541 | B<will> remain available, just the .deb package itself is deleted). |
acbd7bdd |
542 | |
543 | =item * |
544 | |
8168726b |
545 | If you are installing modules from CPAN, you can free up some space with |
546 | "C<rm -rf /root/.cpan/*>" (change "/root/" in the previous command to |
547 | match your home directory or the location where CPAN has been configured |
548 | to perform build operations). |
acbd7bdd |
549 | |
550 | =item * |
551 | |
8168726b |
552 | If necessary, you can remove the cached package information with the |
553 | command "C<rm -f /var/lib/apt/lists/*>". You can later pull this |
acbd7bdd |
554 | information again via the command "C<aptitude update>". |
555 | |
556 | =item * |
557 | |
8168726b |
558 | You can save a small amount of space by commenting out the lines in |
559 | C</etc/apt/sources.list> that reference "deb-src" and |
560 | "security.debian.org". If you have already done an "C<aptitude update>" |
561 | with these repositories enabled, you can use the tip in the previous |
562 | bullet to free the space up (and then do another "C<aptitude update>"). |
acbd7bdd |
563 | |
564 | =item * |
565 | |
8168726b |
566 | Although you can free up space by removing packages you installed since |
a6b4cff5 |
567 | you last booted (check out "C<aptitude remove _pkg_name_>"), don't bother |
8168726b |
568 | trying to remove packages already available at the time of boot. Instead |
a6b4cff5 |
569 | of freeing up space, it will actual consume I<more> space. (The live CD |
8168726b |
570 | uses these "burn in" packages right from the CD disk vs. first loading |
571 | them on the virtual RAM disk. However, if you remove them, the system |
572 | has to update various files, something that I<does> consume some space |
573 | on the virtual RAM disk.) |
acbd7bdd |
574 | |
575 | =back |
576 | |
577 | =back |
578 | |
579 | =item * |
580 | |
1def4a20 |
581 | Ubuntu |
582 | |
a6b4cff5 |
583 | Ubuntu is a popular offshoot of Debian. It provides cutting edge |
584 | versions of many common tools, application and libraries in an |
8168726b |
585 | easy-to-run live CD configuration (and because a single download option |
586 | can be used for both live CD and install-to-disk usage, it keeps your |
587 | download options nice and simple). As with Debian 6, you should be able |
588 | to generate a fully function Catalyst environment in a matter of |
589 | minutes. Here are quick instructions on how to use Ubuntu to prepare |
590 | for the tutorial: |
d442cc9f |
591 | |
592 | =over 4 |
593 | |
594 | =item * |
595 | |
8168726b |
596 | Download the Ubuntu Desktop edition and boot from the CD and/or image |
597 | file, select your language, and then "Try Ubuntu without any changes to |
598 | your computer." |
1def4a20 |
599 | |
600 | =item * |
601 | |
8168726b |
602 | Open a terminal session (click "Applications" in the upper-left corner, |
603 | then "Accessories," then "Terminal"). |
1def4a20 |
604 | |
605 | =item * |
606 | |
607 | Add the 'universe' repositories: |
608 | |
3533daff |
609 | sudo gedit /etc/apt/sources.list |
1def4a20 |
610 | |
611 | And remove the comments from the lines under the comments about the |
612 | 'universe' repositories. |
613 | |
614 | =item * |
615 | |
616 | Install Catalyst: |
617 | |
acbd7bdd |
618 | sudo aptitude update |
619 | sudo aptitude install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl libconfig-general-perl |
1def4a20 |
620 | |
8168726b |
621 | Accept all of the dependencies. Done. |
2b75577c |
622 | |
8168726b |
623 | If you are running from the Live CD, you probably also want to free up |
2b75577c |
624 | some disk space with the following: |
625 | |
acbd7bdd |
626 | sudo aptitude clean |
2b75577c |
627 | |
8168726b |
628 | NOTE: While the instructions above mention the live CD because that |
629 | makes it easy for people new to Linux, you can obviously also use one of |
630 | the options to install Ubuntu on your drive. |
3533daff |
631 | |
1def4a20 |
632 | =back |
633 | |
634 | =item * |
635 | |
d442cc9f |
636 | Matt Trout's C<cat-install> |
637 | |
8168726b |
638 | Available at L<http://www.shadowcat.co.uk/static/cat-install>, |
639 | C<cat-install> can be a fairly painless way to get Catalyst up and |
a6b4cff5 |
640 | running. Just download the script from the link above and type |
641 | C<perl cat-install>. Depending on the speed of your Internet connection |
642 | and your computer, it will probably take 30 to 60 minutes to install |
643 | because it downloads, makes, compiles, and tests every module. But this |
644 | is an excellent way to automate the installation of all the latest |
645 | modules used by Catalyst from CPAN. |
ffeb7448 |
646 | |
d442cc9f |
647 | |
648 | =item * |
649 | |
ffeb7448 |
650 | Other Possibilities |
651 | |
652 | =over 4 |
653 | |
654 | =item * |
655 | |
656 | OpenBSD Packages |
657 | |
8168726b |
658 | The 2008 Advent Day 4 entry has more information on using OpenBSD |
659 | packages to quickly build a system: |
ffeb7448 |
660 | L<http://www.catalystframework.org/calendar/2008/4>. |
661 | |
662 | =item * |
d442cc9f |
663 | |
ffeb7448 |
664 | NetBSD Package Collection on Solaris |
665 | |
8168726b |
666 | The 2008 Advent Day 15 entry has more information on using C<pkgsrc> and |
667 | NetBSD packages on Solaris: |
1435672d |
668 | L<http://www.catalystframework.org/calendar/2008/15>. |
d442cc9f |
669 | |
670 | =item * |
671 | |
ffeb7448 |
672 | CatInABox |
673 | |
8168726b |
674 | You can get more information at |
675 | L<http://www.catalystframework.org/calendar/2008/7> or |
676 | L<Perl::Dist::CatInABox|Perl::Dist::CatInABox>. |
ffeb7448 |
677 | |
0c51850e |
678 | =item * |
679 | |
680 | Frank Speiser's Amazon EC2 Catalyst SDK |
681 | |
682 | There are currently two flavors of publicly available Amazon Machine |
683 | Images (AMI) that include all the elements you'd need to begin |
684 | developing in a fully functional Catalyst environment within minutes. |
685 | See L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> |
686 | for more details. |
687 | |
d442cc9f |
688 | =back |
689 | |
ffeb7448 |
690 | =back |
691 | |
d442cc9f |
692 | For additional information and recommendations on Catalyst installation, |
8168726b |
693 | please refer to |
d442cc9f |
694 | L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>. |
695 | |
1390ef0e |
696 | |
d442cc9f |
697 | =head1 DATABASES |
698 | |
699 | This tutorial will primarily focus on SQLite because of its simplicity |
700 | of installation and use; however, modifications in the script required |
a6b4cff5 |
701 | to support MySQL and PostgreSQL will be presented in the Appendix. |
d442cc9f |
702 | |
a6b4cff5 |
703 | B<Note:> One of the advantages of using tools like Catalyst and DBIC is |
704 | that applications become much more database independent. As such, you |
705 | will notice that only the C<.sql> files used to initialize the database |
706 | change between database systems: most of the code generally remains the |
d442cc9f |
707 | same. |
708 | |
1390ef0e |
709 | |
d442cc9f |
710 | =head1 WHERE TO GET WORKING CODE |
711 | |
8168726b |
712 | Each chapter of the tutorial has complete code available as a tarball in |
713 | the main Catalyst Subversion repository (see the note at the beginning |
028b4e1a |
714 | of each part for the appropriate svn command to use). |
d442cc9f |
715 | |
8168726b |
716 | B<NOTE:> You can run the test cases for the final code through Chapter 8 |
028b4e1a |
717 | with the following commands: |
d442cc9f |
718 | |
0ed3df53 |
719 | svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8 |
720 | cd MyApp_Chapter8/MyApp |
96a87356 |
721 | CATALYST_DEBUG=0 prove -wl t |
d442cc9f |
722 | |
96a87356 |
723 | If you wish to include the L<HTML::FormFu|HTML::FormFu> section in your tests, |
6163536a |
724 | substitute C<MyApp_Chapter9_FormFu> for C<MyApp_Chapter8> in the URL |
725 | above (don't forget to "cd" out of the Ch8 directory if you ran the code above). |
acbd7bdd |
726 | |
0ed3df53 |
727 | svn co http://dev.catalystframework.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter9_FormFu |
728 | cd MyApp_Chapter9_FormFu/MyApp |
96a87356 |
729 | CATALYST_DEBUG=0 prove -wl t |
acbd7bdd |
730 | |
731 | You can also fire up the application under the development server that is conveniently |
732 | built in to Catalyst. Just issue this command from the C<MyApp> directory where you |
733 | ran the test suite above: |
734 | |
735 | script/myapp_server.pl |
736 | |
8168726b |
737 | And the application will start. You can try out the application by |
738 | pulling up C<http://localhost:3000> in your web browser (as mentioned |
739 | earlier, change C<localhost> to a different IP address or DNS name if |
740 | you are running your web browser and your Catalyst development on |
741 | different boxes). We will obviously see more about how to use the |
742 | application as we go through the remaining chapters of the tutorial, but |
743 | for now you can log in using the username "test01" and a password of |
acbd7bdd |
744 | "mypass". |
745 | |
d442cc9f |
746 | |
747 | =head1 AUTHOR |
748 | |
749 | Kennedy Clark, C<hkclark@gmail.com> |
750 | |
8168726b |
751 | Please report any errors, issues or suggestions to the author. The |
752 | most recent version of the Catalyst Tutorial can be found at |
59884771 |
753 | L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>. |
d442cc9f |
754 | |
ec3ef4ad |
755 | Copyright 2006-2010, Kennedy Clark, under the |
756 | Creative Commons Attribution Share-Alike License Version 3.0 |
865d3efb |
757 | (L<http://creativecommons.org/licenses/by-sa/3.0/us/>). |