[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.4 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.4-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] yes
    The following questions are intended to help you with the
    
    ...
    
    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<Note:> You need to have CPAN manually configured prior to running
cat-install.  As shown above, you should automatically receive
a prompt for this when you first run C<perl -MCPAN -e shell>.  You
can re-run the configuration script by typing C<o conf init> at the
C<cpanE<gt>> prompt.

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).  If you want to change the 
selection(s) you made during the "manual configuration" process above, 
you can manually add a single 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 * 

Review the C<cat-install> documentation from the 
L<http://www.shadowcatsystems.co.uk> web site:
    
    If you want to get started quickly with Catalyst, Shadowcat provides an 
    installer script that will automate most of the process of installing it 
    for you. Please bear in mind that this script is currently considered 
    beta quality; we don't think it will eat your system but we make no 
    guarantee of that.
    
    First, you'll need -
    
        * Perl, 5.8.1+ (if you're on windows, get it from Active State)
        * make of some sort. On unix/linux you should already have one. On 
            windows get nmake from Microsoft.
        * A compiler. On unix/linux you should already have one. On windows, 
            get the latest Dev-C++ beta.
        * All three of the above in your PATH for whatever shell you're using
        * A configured CPAN.pm. perl -MCPAN -e shell should get CPAN to walk 
            you through the configuration process
        * Module::Build. Active State kindly include this for you.
    
    Ok, now that your environment is set up, download the installer from 
    this link, open a command prompt in the directory you downloaded it to 
    and run perl cat-install. By the time it exits, you should have a full 
    Catalyst install.
    
    If anything goes wrong, please send the full build log and the output of 
    perl -V to cat-install (at) shadowcatsystems.co.uk so we can try and 
    resolve your issue.


=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('ExtUtils::ParseXS');
    install('Digest::SHA1');
    install('Digest::SHA');
    install('DBIx::Class');
    install('DBIx::Class::HTMLWidget');
    install('Module::ScanDeps');
    install('Module::CoreList');
    install('PAR::Dist');
    install('Archive::Tar');
    install('Module::Install');
    install('Catalyst::Devel');
    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.

Tip: You may want to enable logging of the output that C<cat-install>
generates as it runs -- it can be useful if you need to troubleshoot
a failure.  The log will generate almost 1 MB of output.

Note: Once the C<perl cat-install> is complete, you may want to rerun the 
command to check the status of the packages listed in <cat-install>. Ideally, 
everything should return a I<name> C<is up to date> message.  If any packages 
try to re-install, the you could need to manually install the package with the 
C<force> option.  Also, look for new optional dependencies that C<cat-install>
was not able to automatically handle. You can address these by manually 
installing the dependency and then re-running C<perl cat-install>.  

In some cases you may wish to install an earlier version of a module.  For
example, say that the latest version of Module::Install is 0.64 and you
want to install 0.63.  The following command under C<perl -MCPAN -e shell>:

    cpan> install A/AD/ADAMK/Module-Install-0.63.tar.gz

=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
d02448ef	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');
d02448ef	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
ae29b412	309	C<force> option. Also, look for new optional dependencies that C<cat-install>
d02448ef	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/>).