/ 
Konstrukt-0.5-beta11
River stage zero No dependents
/ Konstrukt::Doc::Installation

NAME

Konstrukt::Doc::Installation - Installation and configuration

INSTALLATION

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

Windows notes

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

On Windows it might be a good idea to install needed perl modules via 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: http://www.google.com/Top/Computers/Programming/Languages/Perl/Win32/PPM_Repositories/, http://cpan.uwinnipeg.ca/htdocs/faqs/ppm.html, http://theoryx5.uwinnipeg.ca/ppms/.

Prerequisites

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

Test dependencies:

  • Module::Build

  • Test::More

  • Test::Pod

  • Test::Pod::Coverage

General dependencies:

  • Clone

  • Cwd

  • CGI

  • Devel::UseAnyFunc

  • MIME::Base64

  • Storable

  • Time::HiRes

  • Time::Zone

Apache/Apache2 dependencies (when using mod_perl -- should be shipped with mod_perl(2)):

Apache/mod_perl:

  • Apache::Constants

Apache2/mod_perl2:

  • Apache2::Const

  • Apache2::Cookie

  • Apache2::RequestIO

  • Apache2::RequestRec

  • Apache2::RequestUtil

Dependencies when using the session management:

  • Session

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

  • DBI

Dependencies when running in debug mode:

  • Data::Dump

Dependencies when sending emails:

  • Digest::HMAC_MD5

  • Mail::Sender

Dependencies of some plugins:

  • Date::Calc

  • Digest::SHA

  • HTTP::BrowserDetect

  • Image::Magick

  • Text::Diff

  • Time::Local

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 http://sial.org/howto/perl/life-with-cpan/non-root/

CONFIGURATION

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>

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.
#When the plugins are preloaded, the pointer to this __DATA__ section will
#be wrong and thus it cannot be read correctly resulting in an invalid
#autoinstallation for these plugins. So you should not preload the plugins
#when running mod_perl2. Preloading of every module without a __DATA__
#section at the end will be safe though.
#PerlRequire /path/to/your/website/KonstruktStartup.pl

#Load handler module
PerlModule Konstrukt::Handler::Apache

#Every .html-file should be handled by the Konstrukt framework.
<FilesMatch "\.html$">
	SetHandler modperl
	PerlResponseHandler Konstrukt::Handler::Apache
</FilesMatch>

Note that you might want to limit the processing of the files only to the files inside your document root. So you might want to put these directives just inside your

<Directory "/path/to/your/docroot">

directive.

The apache module mod_apreq2.so might be needed. So you need a line

LoadModule apreq_module /usr/lib/apache2/modules/mod_apreq2.so

in your config. In Debian, you would just enable the mod like this:

a2enmod apreq

Apache .htaccess configuration

You can put all of these commands in an .htaccess file, but you need

AllowOverride Limit FileInfo

In your vhost. You should also load the preload script directly in the vhost- configuration and not not in an .htaccess (especially, when you specify additional library-paths here):

PerlRequire /path/to/your/website/KonstruktStartup.pl

The rest of the configuration can then be done in the .htaccess.

Other web servers/CGI

As this is currently not really tested (but should work easily) the documentation has yet to be written.

Troubleshooting

If the web server fails to restart, the most common reason is that there is a perl module missing.

Apache will bail out something like this:

[error] Can't locate Apache2/Cookie.pm in @INC [..]

This means that the perl module Apache2::Cookie is missing. You have to install it using CPAN or maybe as a package of your operating system.

Web site specific configuration

All the configuration is done through an "konstrukt.settings"-file in the document root of each website.

Some modules/plugins need a backend, where they store their data. These backends have to be initialized before the first use of the website. There is an auto-installation mechanism, which is turned off by default for performance reasons. You may turn it on before the first use, try out all pages/plugins and turn it off again.

For each plugin you want to use, you may have to define some settings (although the defaults will do in most cases). See below.

Additionally there are some plugin-independent settings which are also explained in the appropriate modules:

The served files can be processed by different handlers, whose configuration is documented in the appropriate modules:

PLUGIN INSTALLATION AND CONFIGURATION

Configuration

There are a lot of plugins that are already bundled with this package. So you don't have to install the modules separately.

But for some plugins you have to specify some settings for them to work. These will be explained in the documentation (CONFIGURATION section) for each plugin. Basically you have to define a database and maybe the template path.

Auto-Installation

Additionally many plugins need some database tables and templates to work correctly. Each plugin has the definitions for those appended at itself. So when using any plugin for the first time, you may want to define:

autoinstall 1

in your konstrukt.settings and load the page containing the plugin. Then the plugins will create the database tables and templates themselves.

Note that your web server needs write-access for your document root. At least as long as the autoinstall option is enabled.

For performance reasons you should turn it off after everything has been installed.

Defaults to 0.

Installation of custom plugins

You may define a path which will be added to the perl library search path in your konstrukt.settings:

lib  /home/someuser/perl/lib;/some/other/perl/lib

There you may put additional plugins that will only be accessible for this website.

You have to use absolute paths - not relative to your document root. Multiple paths may be separated by semicolons.

Defaults to "undefined".

Mailserver Configuration

If your plugins send out emails (usermanagement does, the logging facilities\ eventually do, ...), you may have to adjust your email settings.

As the Konstrukt::Lib core module is used to send emails, you will find a description of the configuration there.

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Next: Konstrukt::Doc::Basics

Previous: Konstrukt::Doc::About

Parent: Konstrukt::Doc