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('DBIx::Class');
 271     install('DBIx::Class::HTMLWidget');
 272     install('Module::ScanDeps');
 273     install('Module::CoreList');
 274     install('PAR::Dist');
 275     install('Archive::Tar');
 276     install('Module::Install');
 277     install('Catalyst::Devel');
 278     install('Catalyst::Plugin::ConfigLoader');
 279     install('Catalyst::Plugin::Session');
 280     install('Catalyst::Plugin::Session::State::Cookie');
 281     install('Catalyst::Plugin::Session::Store::FastMmap');
 282     install('Catalyst::Plugin::Authorization::ACL');
 283     install('Catalyst::Plugin::Authentication');
 284     install('Catalyst::Plugin::Authorization::Roles');
 285     install('Catalyst::Plugin::Authentication::Store::DBIC');
 286     install('Catalyst::Plugin::DefaultEnd');
 287     install('Catalyst::Plugin::StackTrace');
 288     install('Catalyst::Plugin::Dumper');
 289     install('Catalyst::Plugin::HTML::Widget');
 290     install('Catalyst::Model::DBIC::Schema');
 291     install('Catalyst::View::TT');
 292     install('Test::WWW::Mechanize');
 293     install('Test::WWW::Mechanize::Catalyst');
 294     install('Test::Pod');
 295     install('Test::Pod::Coverage');
 296
 297 =item *
 298
 299 Type C<perl cat-install>.  It will take a while to complete.
 300
 301 Tip: You may want to enable logging of the output that C<cat-install>
 302 generates as it runs -- it can be useful if you need to troubleshoot
 303 a failure.  The log will generate almost 1 MB of output.
 304
 305 Note: Once the C<perl cat-install> is complete, you may want to rerun the
 306 command to check the status of the packages listed in <cat-install>. Ideally,
 307 everything should return a I<name> C<is up to date> message.  If any packages
 308 try to re-install, the you could need to manually install the package with the
 309 C<force> option.  Also, look for new optional dependencies that C<cat-install>
 310 was not able to automatically handle. You can address these by manually
 311 installing the dependency and then re-running C<perl cat-install>.
 312
 313 In some cases you may wish to install an earlier version of a module.  For
 314 example, say that the latest version of Module::Install is 0.64 and you
 315 want to install 0.63.  The following command under C<perl -MCPAN -e shell>:
 316
 317     cpan> install A/AD/ADAMK/Module-Install-0.63.tar.gz
 318
 319 =back
 320
 321 You should now have a functioning Catalyst installation with the modules
 322 and plugins required to run the Catalyst tutorial.
 323
 324
 325 =head1 TESTING THE INSTALLATION
 326
 327 =over 4
 328
 329 =item *
 330
 331 Download the tarball of the final tutorial application:
 332
 333     $ wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz
 334
 335 =item *
 336
 337 Untar it:
 338
 339     $ tar zxvf MyApp.tgz
 340     $ cd MyApp
 341
 342 =item *
 343
 344 Run the tests:
 345
 346     $ CATALYST_DEBUG=0 prove --lib lib  t
 347     t/02pod...............skipped
 348             all skipped: set TEST_POD to enable this test
 349     t/03podcoverage.......skipped
 350             all skipped: set TEST_POD to enable this test
 351     t/01app...............ok
 352     t/controller_Login....ok
 353     t/live_app01..........ok 1/0[debug] ***Root::auto User not found, forwarding to /login
 354     t/live_app01..........ok 2/0[debug] ***Root::auto User not found, forwarding to /login
 355     t/live_app01..........ok 15/0[debug] ***Root::auto User not found, forwarding to /login
 356     t/live_app01..........ok 16/0[debug] ***Root::auto User not found, forwarding to /login
 357     t/live_app01..........ok
 358     t/model_MyAppDB.......ok
 359     All tests successful, 2 tests skipped.
 360     Files=6, Tests=55, 11 wallclock secs ( 4.68 cusr +  4.84 csys =  9.52 CPU)
 361
 362 You should see C<All tests successful>.
 363
 364 =back
 365
 366
 367
 368 =head1 AUTHOR
 369
 370 Kennedy Clark, C<hkclark@gmail.com>
 371
 372 Please report any errors, issues or suggestions to the author.  The
 373 most recent version of the Catalyst Tutorial can be found at
 374 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
 375
 376 Copyright 2006, Kennedy Clark, under Creative Commons License
 377 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).