lib/Catalyst/Manual/Installation/CentOS4.pod

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