[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Installation / CentOS4.pod

=head1 NAME

Catalyst::Manual::Installation::CentOS4 - Catalyst Installation on CentOS 4


=head1 DESCRIPTION

This document provides directions on how to install CentOS 4 (a rebuild
of RedHat Enterprise 4) and then install Catalyst.

If you already have a functioning install of CentOS, RHEL, or a
comparable Linux OS, you should be able to skip this first section and
go straight to the C<INSTALL CATALYST> section.

B<NOTE:> You might want to consult the latest version of this document.  It
is available at:
L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Installation/CentOS4.pod>


=head1 INSTALL CENTOS

These directions are written for CentOS 4.3 on an i386 machine; however,
you can substitute other versions as they become available.


=over 4

=item * 

Go to L<http://isoredirect.centos.org/centos/4/isos/i386/> and click the
nearest mirror.

=item * 

Download C<CentOS-4.3-i386-bin1of4.iso> (you only need the first disk).

=item * 

Burn the .iso to CD.

=item * 

Insert the CD into your machine and power it up.

=item * 

Hit C<Enter> at the C<boot:> prompt.

=item * 

CD media test: you can either select C<OK> or C<Skip> depending on
whether or not you trust your burn.

=item * 

The installation GUI should start.  Click next at the "Welcome to
CentOS-4" screen.

=item * 

Select a language and click C<Next>.

=item * 

Select a keyboard configuration and click C<Next>.

=item * 

Select C<Custom> for the installation type and click C<Next>.

=item * 

Leave C<Automatically partition> selected on the C<Disk Partitioning
Setup> and click C<Next>.

=item * 

Uncheck C<Review (and modify if needed) the partitions created>, but
leave the rest of the default settings on the C<Automatic Partitioning>
screen.  Then click C<Next>.

=item * 

Click C<Yes> at the C<Are you sure you want to do this?> warning.

=item * 

Click C<Next> on the C<Boot Loader Configuration> screen.

=item * 

Update the C<Network Configuration> screen as necessary and click C<Next>.

=item * 

Check C<Remote Login (SSH)> and click C<Next> on the C<Firewall
Configuration> screen.

=item * 

Select additional languages as necessary.  Click C<Next>.

=item * 

Select the appropriate time zone and click C<Next>.

=item * 

Enter a root password and click C<Next>.

=item * 

Scroll to the bottom of the C<Package Group Selection> screen and check
C<Minimal> (the last option).  Click C<Next>.

=item * 

Click C<Next> at the C<About to Install> screen.

=item * 

The installation will prepare the hard drive and then install the
required rpm packages.

=item * 

Once the installation completes, remove the CD and click C<Reboot>.

=item * 

Type C<vi /etc/sysconfig/iptables> and add the following line as the
third to last line of the file (I<above> the C<-A RH-Firewall-1-INPUT -j
REJECT --reject-with icmp-host-prohibited> line):

    -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 3000 -j ACCEPT

This will allow Catalyst to make use of port 3000 (the default for the
development server).

Type C<service iptables restart> to restart the iptables firewall using
the updated configuration.

=item * 

Type C<yum -y update> to retrieve the latest patches.

=back


=head1 INSTALL CATALYST

=over 4

=item * 

Type C<yum -y install gcc expat-devel sqlite3> to install several
packages used by Catalyst.

=item * 

Type the following:

    $ perl -MCPAN -e shell
    
    ...
    
    Are you ready for manual configuration? [yes] n
    
    ...
    
    cpan shell -- CPAN exploration and modules installation (v1.7601)
    ReadLine support available (try 'install Bundle::CPAN')
        
    cpan> force install Module::Build
    
    ...
    
    cpan> quit

=item *

B<Optional:> The remaining steps of the installation could run 
significantly faster if you configure a fast mirror that uses HTTP vs. 
FTP (both transfer data at the same rate once the transfer is in 
progress, but HTTP connects much more quickly... and a Catalyst 
installation involves many connections).  One way to do this is to 
answer C<yes> to the C<Are you ready for manual configuration?> prompt 
when you ran C<perl -MCPAN -e shell> above.  Or, you can rerun the 
script by entering the following command at the C<cpanE<gt>> prompt:

    cpan> o conf init

It will then take you through the configuration dialog.  

However, it's often easiesr to avoid the full configuration dialog and
manually add a URL.  To prepend a new URL to the B<front> of the list,
use the C<unshift> option to C<o conf>:

    cpan> o conf urllist unshift http://www.perl.com/CPAN/

Where C<http://www.perl.com/CPAN/> is replaced by a nearby, HTTP-based 
mirror.  You can get a list of all mirrors (including where they are 
located, their bandwidth, and their update frequency) at 
L<http://www.perl.com/CPAN/MIRRORED.BY>.

Then, be sure to save your changes (or they will be lost the next
time you restart the CPAN shell):

    cpan> o conf commit

You can view the current settings with C<o conf urllist> (or just
C<o conf> to view all settings):

    cpan> o conf urllist
        urllist           
            http://www.perl.com/CPAN/
    Type 'o conf' to view configuration edit options
 
Note that multiple values can be entered for the C<urllist> option (the
first entry will be used as long as it responds).

=item * 

Type C<wget http://www.shadowcatsystems.co.uk/static/cat-install> to
retrieve a copy of the C<cat-install> script.

=item * 

Type C<vi cat-install> to open the installer script, then insert the
following lines at the bottom of the file (after the
C<install('Catalyst');> line):

    install('Catalyst::Devel');
    install('ExtUtils::ParseXS');
    install('Digest::SHA1');
    install('Digest::SHA');
    install('Class::DBI');
    install('DBIx::Class');
    install('DBIx::Class::HTMLWidget');
    install('Module::Install');
    install('Catalyst::Plugin::ConfigLoader');
    install('Catalyst::Plugin::Session');
    install('Catalyst::Plugin::Session::State::Cookie');
    install('Catalyst::Plugin::Session::Store::FastMmap');
    install('Catalyst::Plugin::Authorization::ACL');
    install('Catalyst::Plugin::Authentication');
    install('Catalyst::Plugin::Authorization::Roles');
    install('Catalyst::Plugin::Authentication::Store::DBIC');
    install('Catalyst::Plugin::DefaultEnd');
    install('Catalyst::Plugin::StackTrace');
    install('Catalyst::Plugin::Dumper');
    install('Catalyst::Plugin::HTML::Widget');
    install('Catalyst::Model::DBIC::Schema');
    install('Catalyst::View::TT');
    install('Test::WWW::Mechanize');
    install('Test::WWW::Mechanize::Catalyst');
    install('Test::Pod');
    install('Test::Pod::Coverage');

=item * 

Type C<perl cat-install>.  It will take a while to complete.

=back

You should now have a functioning Catalyst installation with the modules
and plugins required to run the Catalyst tutorial.


=head1 TESTING THE INSTALLATION

=over 4

=item *

Download the tarball of the final tutorial application:

    $ wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz

=item *

Untar it:

    $ tar zxvf MyApp.tgz
    $ cd MyApp

=item *

Run the tests:

    $ CATALYST_DEBUG=0 prove --lib lib  t
    t/02pod...............skipped
            all skipped: set TEST_POD to enable this test
    t/03podcoverage.......skipped
            all skipped: set TEST_POD to enable this test
    t/01app...............ok                                                     
    t/controller_Login....ok                                                     
    t/live_app01..........ok 1/0[debug] ***Root::auto User not found, forwarding to /login
    t/live_app01..........ok 2/0[debug] ***Root::auto User not found, forwarding to /login
    t/live_app01..........ok 15/0[debug] ***Root::auto User not found, forwarding to /login
    t/live_app01..........ok 16/0[debug] ***Root::auto User not found, forwarding to /login
    t/live_app01..........ok                                                     
    t/model_MyAppDB.......ok                                                     
    All tests successful, 2 tests skipped.
    Files=6, Tests=55, 11 wallclock secs ( 4.68 cusr +  4.84 csys =  9.52 CPU)

You should see C<All tests successful>.

=back


=head1 AUTHOR

Kennedy Clark, C<hkclark@gmail.com>

Please report any errors, issues or suggestions to the author.  The
most recent version of the Catalyst Tutorial can be found at
L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.

Copyright 2006, Kennedy Clark, under Creative Commons License
(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
Commit	Line	Data
4d583dd8	1	=head1 NAME
4d583dd8	2
64ccd8a8	3	Catalyst::Manual::Installation::CentOS4 - Catalyst Installation on CentOS 4
4d583dd8	4
	5
	6
	7	=head1 DESCRIPTION
	8
64ccd8a8	9	This document provides directions on how to install CentOS 4 (a rebuild
64ccd8a8	10	of RedHat Enterprise 4) and then install Catalyst.
4d583dd8	11
64ccd8a8	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.
4d583dd8	15
d645910d	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
4d583dd8	21
	22	=head1 INSTALL CENTOS
	23
64ccd8a8	24	These directions are written for CentOS 4.3 on an i386 machine; however,
64ccd8a8	25	you can substitute other versions as they become available.
4d583dd8	26
	27
	28	=over 4
	29
	30	=item *
	31
64ccd8a8	32	Go to L<http://isoredirect.centos.org/centos/4/isos/i386/> and click the
64ccd8a8	33	nearest mirror.
4d583dd8	34
	35	=item *
	36
	37	Download C<CentOS-4.3-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
64ccd8a8	53	CD media test: you can either select C<OK> or C<Skip> depending on
64ccd8a8	54	whether or not you trust your burn.
4d583dd8	55
	56	=item *
	57
64ccd8a8	58	The installation GUI should start. Click next at the "Welcome to
64ccd8a8	59	CentOS-4" screen.
4d583dd8	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
64ccd8a8	75	Leave C<Automatically partition> selected on the C<Disk Partitioning
64ccd8a8	76	Setup> and click C<Next>.
4d583dd8	77
	78	=item *
	79
64ccd8a8	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>.
4d583dd8	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
64ccd8a8	98	Check C<Remote Login (SSH)> and click C<Next> on the C<Firewall
64ccd8a8	99	Configuration> screen.
4d583dd8	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
64ccd8a8	115	Scroll to the bottom of the C<Package Group Selection> screen and check
64ccd8a8	116	C<Minimal> (the last option). Click C<Next>.
4d583dd8	117
	118	=item *
	119
	120	Click C<Next> at the C<About to Install> screen.
	121
	122	=item *
	123
64ccd8a8	124	The installation will prepare the hard drive and then install the
64ccd8a8	125	required rpm packages.
4d583dd8	126
	127	=item *
	128
	129	Once the installation completes, remove the CD and click C<Reboot>.
	130
	131	=item *
	132
64ccd8a8	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):
4d583dd8	136
	137	-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 3000 -j ACCEPT
	138
64ccd8a8	139	This will allow Catalyst to make use of port 3000 (the default for the
64ccd8a8	140	development server).
4d583dd8	141
64ccd8a8	142	Type C<service iptables restart> to restart the iptables firewall using
64ccd8a8	143	the updated configuration.
4d583dd8	144
	145	=item *
	146
64ccd8a8	147	Type 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	158	Type C<yum -y install gcc expat-devel sqlite3> to install several
64ccd8a8	159	packages used by Catalyst.
4d583dd8	160
	161	=item *
	162
	163	Type the following:
	164
ce1dd321	165	$ perl -MCPAN -e shell
4d583dd8	166
	167	...
	168
	169	Are you ready for manual configuration? [yes] n
	170
	171	...
	172
	173	cpan shell -- CPAN exploration and modules installation (v1.7601)
	174	ReadLine support available (try 'install Bundle::CPAN')
315ba149	175
4d583dd8	176	cpan> force install Module::Build
	177
	178	...
	179
	180	cpan> quit
	181
ce1dd321	182	=item *
	183
	184	B<Optional:> The remaining steps of the installation could run
	185	significantly faster if you configure a fast mirror that uses HTTP vs.
	186	FTP (both transfer data at the same rate once the transfer is in
	187	progress, but HTTP connects much more quickly... and a Catalyst
	188	installation involves many connections). One way to do this is to
	189	answer C<yes> to the C<Are you ready for manual configuration?> prompt
	190	when you ran C<perl -MCPAN -e shell> above. Or, you can rerun the
	191	script by entering the following command at the C<cpanE<gt>> prompt:
	192
	193	cpan> o conf init
	194
	195	It will then take you through the configuration dialog.
	196
d532d354	197	However, it's often easiesr to avoid the full configuration dialog and
	198	manually add a URL. To prepend a new URL to the B<front> of the list,
	199	use the C<unshift> option to C<o conf>:
	200
	201	cpan> o conf urllist unshift http://www.perl.com/CPAN/
ce1dd321	202
	203	Where C<http://www.perl.com/CPAN/> is replaced by a nearby, HTTP-based
	204	mirror. You can get a list of all mirrors (including where they are
	205	located, their bandwidth, and their update frequency) at
	206	L<http://www.perl.com/CPAN/MIRRORED.BY>.
	207
d532d354	208	Then, be sure to save your changes (or they will be lost the next
	209	time you restart the CPAN shell):
	210
	211	cpan> o conf commit
	212
	213	You can view the current settings with C<o conf urllist> (or just
	214	C<o conf> to view all settings):
	215
	216	cpan> o conf urllist
	217	urllist
	218	http://www.perl.com/CPAN/
	219	Type 'o conf' to view configuration edit options
	220
	221	Note that multiple values can be entered for the C<urllist> option (the
	222	first entry will be used as long as it responds).
	223
4d583dd8	224	=item *
4d583dd8	225
64ccd8a8	226	Type C<wget http://www.shadowcatsystems.co.uk/static/cat-install> to
64ccd8a8	227	retrieve a copy of the C<cat-install> script.
4d583dd8	228
	229	=item *
	230
64ccd8a8	231	Type C<vi cat-install> to open the installer script, then insert the
	232	following lines at the bottom of the file (after the
	233	C<install('Catalyst');> line):
4d583dd8	234
fcf42995	235	install('Catalyst::Devel');
315ba149	236	install('ExtUtils::ParseXS');
97ed9466	237	install('Digest::SHA1');
315ba149	238	install('Digest::SHA');
4d583dd8	239	install('Class::DBI');
	240	install('DBIx::Class');
	241	install('DBIx::Class::HTMLWidget');
ce1dd321	242	install('Module::Install');
ce1dd321	243	install('Catalyst::Plugin::ConfigLoader');
4d583dd8	244	install('Catalyst::Plugin::Session');
	245	install('Catalyst::Plugin::Session::State::Cookie');
	246	install('Catalyst::Plugin::Session::Store::FastMmap');
	247	install('Catalyst::Plugin::Authorization::ACL');
	248	install('Catalyst::Plugin::Authentication');
	249	install('Catalyst::Plugin::Authorization::Roles');
	250	install('Catalyst::Plugin::Authentication::Store::DBIC');
	251	install('Catalyst::Plugin::DefaultEnd');
	252	install('Catalyst::Plugin::StackTrace');
	253	install('Catalyst::Plugin::Dumper');
315ba149	254	install('Catalyst::Plugin::HTML::Widget');
4d583dd8	255	install('Catalyst::Model::DBIC::Schema');
4d583dd8	256	install('Catalyst::View::TT');
ce1dd321	257	install('Test::WWW::Mechanize');
4d583dd8	258	install('Test::WWW::Mechanize::Catalyst');
315ba149	259	install('Test::Pod');
315ba149	260	install('Test::Pod::Coverage');
4d583dd8	261
	262	=item *
	263
	264	Type C<perl cat-install>. It will take a while to complete.
	265
	266	=back
	267
64ccd8a8	268	You should now have a functioning Catalyst installation with the modules
64ccd8a8	269	and plugins required to run the Catalyst tutorial.
4d583dd8	270
4d583dd8	271
ce1dd321	272	=head1 TESTING THE INSTALLATION
	273
	274	=over 4
	275
	276	=item *
	277
	278	Download the tarball of the final tutorial application:
	279
	280	$ wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz
	281
	282	=item *
	283
	284	Untar it:
	285
	286	$ tar zxvf MyApp.tgz
	287	$ cd MyApp
	288
	289	=item *
	290
	291	Run the tests:
	292
	293	$ CATALYST_DEBUG=0 prove --lib lib t
	294	t/02pod...............skipped
	295	all skipped: set TEST_POD to enable this test
	296	t/03podcoverage.......skipped
	297	all skipped: set TEST_POD to enable this test
	298	t/01app...............ok
	299	t/controller_Login....ok
	300	t/live_app01..........ok 1/0[debug] ***Root::auto User not found, forwarding to /login
	301	t/live_app01..........ok 2/0[debug] ***Root::auto User not found, forwarding to /login
	302	t/live_app01..........ok 15/0[debug] ***Root::auto User not found, forwarding to /login
	303	t/live_app01..........ok 16/0[debug] ***Root::auto User not found, forwarding to /login
	304	t/live_app01..........ok
	305	t/model_MyAppDB.......ok
	306	All tests successful, 2 tests skipped.
	307	Files=6, Tests=55, 11 wallclock secs ( 4.68 cusr + 4.84 csys = 9.52 CPU)
	308
	309	You should see C<All tests successful>.
	310
	311	=back
	312
	313
	314
4d583dd8	315	=head1 AUTHOR
	316
	317	Kennedy Clark, C<hkclark@gmail.com>
	318
d645910d	319	Please report any errors, issues or suggestions to the author. The
7d310f12	320	most recent version of the Catalyst Tutorial can be found at
d645910d	321	L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
4d583dd8	322
64ccd8a8	323	Copyright 2006, Kennedy Clark, under Creative Commons License
64ccd8a8	324	(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).