doh
[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Installation / CentOS4.pod
CommitLineData
4d583dd8 1=head1 NAME
2
64ccd8a8 3Catalyst::Manual::Installation::CentOS4 - Catalyst Installation on CentOS 4
4d583dd8 4
5
6
7=head1 DESCRIPTION
8
64ccd8a8 9This document provides directions on how to install CentOS 4 (a rebuild
10of RedHat Enterprise 4) and then install Catalyst.
4d583dd8 11
64ccd8a8 12If you already have a functioning install of CentOS, RHEL, or a
13comparable Linux OS, you should be able to skip this first section and
14go straight to the C<INSTALL CATALYST> section.
4d583dd8 15
d645910d 16B<NOTE:> You might want to consult the latest version of this document. It
17is available at:
18L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Installation/CentOS4.pod>
19
20
4d583dd8 21
22=head1 INSTALL CENTOS
23
7dcf1650 24These directions are written for CentOS 4.4 on an i386 machine; however,
64ccd8a8 25you can substitute other versions as they become available.
4d583dd8 26
27
28=over 4
29
30=item *
31
64ccd8a8 32Go to L<http://isoredirect.centos.org/centos/4/isos/i386/> and click the
33nearest mirror.
4d583dd8 34
35=item *
36
7dcf1650 37Download C<CentOS-4.4-i386-bin1of4.iso> (you only need the first disk).
4d583dd8 38
39=item *
40
41Burn the .iso to CD.
42
43=item *
44
45Insert the CD into your machine and power it up.
46
47=item *
48
49Hit C<Enter> at the C<boot:> prompt.
50
51=item *
52
64ccd8a8 53CD media test: you can either select C<OK> or C<Skip> depending on
54whether or not you trust your burn.
4d583dd8 55
56=item *
57
64ccd8a8 58The installation GUI should start. Click next at the "Welcome to
59CentOS-4" screen.
4d583dd8 60
61=item *
62
63Select a language and click C<Next>.
64
65=item *
66
67Select a keyboard configuration and click C<Next>.
68
69=item *
70
71Select C<Custom> for the installation type and click C<Next>.
72
73=item *
74
64ccd8a8 75Leave C<Automatically partition> selected on the C<Disk Partitioning
76Setup> and click C<Next>.
4d583dd8 77
78=item *
79
64ccd8a8 80Uncheck C<Review (and modify if needed) the partitions created>, but
81leave the rest of the default settings on the C<Automatic Partitioning>
82screen. Then click C<Next>.
4d583dd8 83
84=item *
85
86Click C<Yes> at the C<Are you sure you want to do this?> warning.
87
88=item *
89
90Click C<Next> on the C<Boot Loader Configuration> screen.
91
92=item *
93
94Update the C<Network Configuration> screen as necessary and click C<Next>.
95
96=item *
97
64ccd8a8 98Check C<Remote Login (SSH)> and click C<Next> on the C<Firewall
99Configuration> screen.
4d583dd8 100
101=item *
102
103Select additional languages as necessary. Click C<Next>.
104
105=item *
106
107Select the appropriate time zone and click C<Next>.
108
109=item *
110
111Enter a root password and click C<Next>.
112
113=item *
114
64ccd8a8 115Scroll to the bottom of the C<Package Group Selection> screen and check
116C<Minimal> (the last option). Click C<Next>.
4d583dd8 117
118=item *
119
120Click C<Next> at the C<About to Install> screen.
121
122=item *
123
64ccd8a8 124The installation will prepare the hard drive and then install the
125required rpm packages.
4d583dd8 126
127=item *
128
129Once the installation completes, remove the CD and click C<Reboot>.
130
131=item *
132
64ccd8a8 133Type C<vi /etc/sysconfig/iptables> and add the following line as the
134third to last line of the file (I<above> the C<-A RH-Firewall-1-INPUT -j
135REJECT --reject-with icmp-host-prohibited> line):
4d583dd8 136
137 -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 3000 -j ACCEPT
138
64ccd8a8 139This will allow Catalyst to make use of port 3000 (the default for the
140development server).
4d583dd8 141
64ccd8a8 142Type C<service iptables restart> to restart the iptables firewall using
143the updated configuration.
4d583dd8 144
145=item *
146
64ccd8a8 147Type C<yum -y update> to retrieve the latest patches.
4d583dd8 148
149=back
150
151
152=head1 INSTALL CATALYST
153
154=over 4
155
156=item *
157
97ed9466 158Type C<yum -y install gcc expat-devel sqlite3> to install several
64ccd8a8 159packages used by Catalyst.
4d583dd8 160
161=item *
162
163Type the following:
164
ce1dd321 165 $ perl -MCPAN -e shell
4d583dd8 166
167 ...
168
d901e2e2 169 Are you ready for manual configuration? [yes] yes
170 The following questions are intended to help you with the
4d583dd8 171
172 ...
173
174 cpan shell -- CPAN exploration and modules installation (v1.7601)
175 ReadLine support available (try 'install Bundle::CPAN')
315ba149 176
4d583dd8 177 cpan> force install Module::Build
178
179 ...
180
181 cpan> quit
182
ce1dd321 183=item *
184
d901e2e2 185B<Note:> You need to have CPAN manually configured prior to running
186cat-install. As shown above, you should automatically receive
187a prompt for this when you first run C<perl -MCPAN -e shell>. You
188can re-run the configuration script by typing C<o conf init> at the
189C<cpanE<gt>> prompt.
190
ce1dd321 191B<Optional:> The remaining steps of the installation could run
192significantly faster if you configure a fast mirror that uses HTTP vs.
193FTP (both transfer data at the same rate once the transfer is in
194progress, but HTTP connects much more quickly... and a Catalyst
d901e2e2 195installation involves many connections). If you want to change the
196selection(s) you made during the "manual configuration" process above,
197you can manually add a single URL. To prepend a new URL to the B<front>
198of the list, use the C<unshift> option to C<o conf>:
d532d354 199
200 cpan> o conf urllist unshift http://www.perl.com/CPAN/
ce1dd321 201
202Where C<http://www.perl.com/CPAN/> is replaced by a nearby, HTTP-based
203mirror. You can get a list of all mirrors (including where they are
204located, their bandwidth, and their update frequency) at
205L<http://www.perl.com/CPAN/MIRRORED.BY>.
206
d532d354 207Then, be sure to save your changes (or they will be lost the next
208time you restart the CPAN shell):
209
210 cpan> o conf commit
211
212You can view the current settings with C<o conf urllist> (or just
213C<o conf> to view all settings):
214
215 cpan> o conf urllist
216 urllist
217 http://www.perl.com/CPAN/
218 Type 'o conf' to view configuration edit options
219
220Note that multiple values can be entered for the C<urllist> option (the
221first entry will be used as long as it responds).
222
4d583dd8 223=item *
224
d901e2e2 225Review the C<cat-install> documentation from the
226L<http://www.shadowcatsystems.co.uk> web site:
227
228 If you want to get started quickly with Catalyst, Shadowcat provides an
229 installer script that will automate most of the process of installing it
230 for you. Please bear in mind that this script is currently considered
231 beta quality; we don't think it will eat your system but we make no
232 guarantee of that.
233
234 First, you'll need -
235
236 * Perl, 5.8.1+ (if you're on windows, get it from Active State)
237 * make of some sort. On unix/linux you should already have one. On
238 windows get nmake from Microsoft.
239 * A compiler. On unix/linux you should already have one. On windows,
240 get the latest Dev-C++ beta.
241 * All three of the above in your PATH for whatever shell you're using
242 * A configured CPAN.pm. perl -MCPAN -e shell should get CPAN to walk
243 you through the configuration process
244 * Module::Build. Active State kindly include this for you.
245
246 Ok, now that your environment is set up, download the installer from
247 this link, open a command prompt in the directory you downloaded it to
248 and run perl cat-install. By the time it exits, you should have a full
249 Catalyst install.
250
251 If anything goes wrong, please send the full build log and the output of
252 perl -V to cat-install (at) shadowcatsystems.co.uk so we can try and
253 resolve your issue.
254
255
256=item *
257
64ccd8a8 258Type C<wget http://www.shadowcatsystems.co.uk/static/cat-install> to
259retrieve a copy of the C<cat-install> script.
4d583dd8 260
261=item *
262
64ccd8a8 263Type C<vi cat-install> to open the installer script, then insert the
264following lines at the bottom of the file (after the
265C<install('Catalyst');> line):
4d583dd8 266
315ba149 267 install('ExtUtils::ParseXS');
97ed9466 268 install('Digest::SHA1');
315ba149 269 install('Digest::SHA');
4d583dd8 270 install('Class::DBI');
271 install('DBIx::Class');
272 install('DBIx::Class::HTMLWidget');
7dcf1650 273 install('Module::ScanDeps');
274 install('Module::CoreList');
275 install('PAR::Dist');
276 install('Archive::Tar');
ce1dd321 277 install('Module::Install');
7dcf1650 278 install('Catalyst::Devel');
ce1dd321 279 install('Catalyst::Plugin::ConfigLoader');
4d583dd8 280 install('Catalyst::Plugin::Session');
281 install('Catalyst::Plugin::Session::State::Cookie');
282 install('Catalyst::Plugin::Session::Store::FastMmap');
283 install('Catalyst::Plugin::Authorization::ACL');
284 install('Catalyst::Plugin::Authentication');
285 install('Catalyst::Plugin::Authorization::Roles');
286 install('Catalyst::Plugin::Authentication::Store::DBIC');
287 install('Catalyst::Plugin::DefaultEnd');
288 install('Catalyst::Plugin::StackTrace');
289 install('Catalyst::Plugin::Dumper');
315ba149 290 install('Catalyst::Plugin::HTML::Widget');
4d583dd8 291 install('Catalyst::Model::DBIC::Schema');
292 install('Catalyst::View::TT');
ce1dd321 293 install('Test::WWW::Mechanize');
4d583dd8 294 install('Test::WWW::Mechanize::Catalyst');
315ba149 295 install('Test::Pod');
296 install('Test::Pod::Coverage');
4d583dd8 297
298=item *
299
300Type C<perl cat-install>. It will take a while to complete.
301
7dcf1650 302Tip: You may want to enable logging of the output that C<cat-install>
303generates as it runs -- it can be useful if you need to troubleshoot
304a failure. The log will generate almost 1 MB of output.
305
306Note: Once the C<perl cat-install> is complete, you may want to rerun the
307command to check the status of the packages listed in <cat-install>. Ideally,
308everything should return a I<name> C<is up to date> message. If any packages
309try to re-install, the you could need to manually install the package with the
310C<force> option. Also, look for new optional dependences that C<cat-install>
311was not able to automatically handle. You can address these by manually
312installing the dependency and then re-running C<perl cat-install>.
313
314In some cases you may wish to install an earlier version of a module. For
315example, say that the latest version of Module::Install is 0.64 and you
316want to install 0.63. The following command under C<perl -MCPAN -e shell>:
317
318 cpan> install A/AD/ADAMK/Module-Install-0.63.tar.gz
319
4d583dd8 320=back
321
64ccd8a8 322You should now have a functioning Catalyst installation with the modules
323and plugins required to run the Catalyst tutorial.
4d583dd8 324
325
ce1dd321 326=head1 TESTING THE INSTALLATION
327
328=over 4
329
330=item *
331
332Download the tarball of the final tutorial application:
333
334 $ wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz
335
336=item *
337
338Untar it:
339
340 $ tar zxvf MyApp.tgz
341 $ cd MyApp
342
343=item *
344
345Run the tests:
346
347 $ CATALYST_DEBUG=0 prove --lib lib t
348 t/02pod...............skipped
349 all skipped: set TEST_POD to enable this test
350 t/03podcoverage.......skipped
351 all skipped: set TEST_POD to enable this test
352 t/01app...............ok
353 t/controller_Login....ok
354 t/live_app01..........ok 1/0[debug] ***Root::auto User not found, forwarding to /login
355 t/live_app01..........ok 2/0[debug] ***Root::auto User not found, forwarding to /login
356 t/live_app01..........ok 15/0[debug] ***Root::auto User not found, forwarding to /login
357 t/live_app01..........ok 16/0[debug] ***Root::auto User not found, forwarding to /login
358 t/live_app01..........ok
359 t/model_MyAppDB.......ok
360 All tests successful, 2 tests skipped.
361 Files=6, Tests=55, 11 wallclock secs ( 4.68 cusr + 4.84 csys = 9.52 CPU)
362
363You should see C<All tests successful>.
364
365=back
366
367
368
4d583dd8 369=head1 AUTHOR
370
371Kennedy Clark, C<hkclark@gmail.com>
372
d645910d 373Please report any errors, issues or suggestions to the author. The
7d310f12 374most recent version of the Catalyst Tutorial can be found at
d645910d 375L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
4d583dd8 376
64ccd8a8 377Copyright 2006, Kennedy Clark, under Creative Commons License
378(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).