view release on metacpan or  search on metacpan

lib/Konstrukt/Doc/Installation.pod  view on Meta::CPAN

#TODO: Update list of dependencies
#TODO: documentataion for CGI configuration

=head1 NAME

Konstrukt::Doc::Installation - Installation and configuration

=head1 INSTALLATION

=head2 Module installation (from source)

This will be done just as with every other perl module (will probably vary in
Windows):

	tar -xvzf Konstrukt-X.Y.tar.gz
	cd Konstrukt-X.Y
	perl Build.PL
	./Build
	./Build test
	./Build install

As several other modules are used you might have to install other perl modules
first, which is done best via CPAN.

On most (modern) systems you can open the cpan console just with the cpan
command:

	# cpan
	cpan> install Some::Module

You may also specify the modules you want to install at the command line:

	# cpan Some::Module

So a shortcut to install a recommended set of modules would be

	# cpan Module::Build CGI Storable Time::HiRes Scalar::Util::Clone Session DBI DBD::mysql \
	Data::Dump Date::Calc Digest::SHA HTTP::BrowserDetect Image::Magick \
	Text::Diff Time::Local Time::Zone

Note that it might be better to install some modules from the package manager
of your operating system.

On Debian for example there are several packages for common perl modules
available (e.g. Image::Magick -> perlmagick; DBD::mysql ->
lib-dbd-mysql-perl; DBI -> libdbi-perl; CGI -> libCGI-perl; Apache ->
libapache-dbi-perl, libapache-request-perl, libapache-session-perl;
Apache2 -> libapache2-mod-apreq2, libapache2-mod-perl2).

On some systems you might have to call CPAN via a perl command:

	# perl -MCPAN -e shell

=head2 Windows notes

First of all, C<./Build> as stated above will most probably not work.
You must run it like this: C<perl Build>.

On B<Windows> it might be a good idea to install needed perl modules via C<ppm>
(note the hyphen instead of the double colons):

	C:\> ppm
	ppm> install Some-Module
	
Or short:

	C:\>ppm install Some-Module

As the (default) ActiveState repositories might miss some modules, you can try to
add additional repositories:

	ppm> rep add <name> <url>

Info about and lists of some repositories can be found here:
L<http://www.google.com/Top/Computers/Programming/Languages/Perl/Win32/PPM_Repositories/>,
L<http://cpan.uwinnipeg.ca/htdocs/faqs/ppm.html>,
L<http://theoryx5.uwinnipeg.ca/ppms/>.

=head2 Prerequisites

This is a (hopefully) complete list of 3rd-party perl modules used in this framework.

B<Test dependencies:>

=over

=item * Module::Build

=item * Test::More

=item * Test::Pod

=item * Test::Pod::Coverage

=back

B<General dependencies:>

=over

=item * Clone

=item * Cwd

=item * CGI

lib/Konstrukt/Doc/Installation.pod  view on Meta::CPAN

=over

=item * Apache2::Const

=item * Apache2::Cookie

=item * Apache2::RequestIO

=item * Apache2::RequestRec

=item * Apache2::RequestUtil

=back

B<Dependencies when using the session management:>

=over

=item * Session

=back

B<Dependencies when using the database connection management (which most plugins
use):>

=over

=item * DBI

=back

B<Dependencies when running in debug mode:>

=over

=item * Data::Dump

=back

B<Dependencies when sending emails:>

=over

=item * Digest::HMAC_MD5

=item * Mail::Sender

=back

B<Dependencies of some plugins:>

=over

=item * Date::Calc

=item * Digest::SHA

=item * HTTP::BrowserDetect

=item * Image::Magick

=item * Text::Diff

=item * Time::Local

=back

=head2 Local Module installation (non-root)

Basically the same as above, with some differences:

	tar -xvzf Konstrukt-X.Y.tar.gz
	cd Konstrukt-X.Y
	perl Build.PL --install_base $HOME/perl
	./Build
	./Build test
	./Build install

Using CPAN for local installation: You might want to take a look at
L<http://sial.org/howto/perl/life-with-cpan/non-root/>

=head1 CONFIGURATION

=head2 Apache configuration

Basically the configuration inside an apache vhost would look like this:

	#Do not allow access to *.template, *.form and konstrukt.setting files
	<FilesMatch "(\.template|\.form|konstrukt\.settings)$">
		Deny from All
	</FilesMatch>
	
	#Preload script. Will load all modules on server startup.
	#An example is provided in the scripts/ directory of the distribution package.
	#The modules to preload may vary with the plugins you want to use.
	#You can also just comment this line out, which will lead in a bit more
	#memory usage of your apache.
	PerlRequire /path/to/your/website/KonstruktStartup.pl
	
	#Every .html-file should be handled by the Konstrukt framework.
	#You may also define other file types as well.
	<FilesMatch "\.html$">
		SetHandler perl-script
		PerlHandler Konstrukt::Handler::Apache
	</FilesMatch>

=head2 Apache2 configuration

This is similar, but a bit different to the apache configuration and will look
like this:
	
	#Do not allow access to *.template, *.form and konstrukt.setting files
	<FilesMatch "(\.template|\.form|konstrukt\.settings)$">
		Deny from All
	</FilesMatch>
	
	#Preload script. Description see above at Apache configuration.
	#WARNING: There seems to be a bug in mod_perl2 when modules are preloaded:
	#Many Konstrukt plugins store their default DB table definitions and
	#templates in a __DATA__ section at the end of the file.