NAME

Contentment::Manual::Install - The installation guide for Contentment

SYNOPSIS

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

DESCRIPTION

The synopsis is pretty bare and you will almost certainly need to be a little more particular with out Build.PL is run. After installation you will also need to create the configuration files and may also need to create an additional CGI script to help you set things up. You may also need to modify your Apache web server configuration or .htaccess files in the installation directories.

Build.PL OPTIONS

Contentment is not a standard CPAN install. However, it is meant to be relatively easy to install. Obviously, we're not there yet if writing an additional CGI script and .htaccess file are still necessary, but as of version 0.9.0, great strides have been made to improve the install process.

Install Base

Without any options, Contentment will be installed to /usr/local/Contentment which is a reasonable default location, but probably not a good place for most production environments. If you want this to go to a different location, you merely need to specify the install_base option to Build.PL:

  perl Build.PL install_base=/var/www/Contentment

Relocation

This is probably not enough if you are installing on a hosted environment or a server where the policies can't be altered. Typically, I've found that I need to relocate two specific directories depending upon the policies of the host. For example, if you scripts are going to be running within suexec, you'll need the CGI scripts to be moved under the Apache document root. To make relocations, you use the --install_path option:

  perl Build.PL install_base=/web/support  \
      --install_path cgi-bin=/var/www/localhost/cgi-bin

If you are installing into a home directory, you might need to be even more particular:

  perl Build.PL install_base=/home/sterling \
      --install_path docroots/master=/home/sterling/contentment.org \
      --install_path cgi-bin=/home/sterling/contentment.org/cgi-bin

You should be able to relocate any directory within the Contentment installation this way.

EDIT CONFIGURATION

The configuration is stored in three files, all stored in etc: Contentment.conf, Contentment.defaults.conf, and log4perl.conf. The Contentment.defaults.conf file is created automatically and shouldn't overwritten. This file is updated and replaced when installing updated versions of Contentment.

The Contentment.conf file specifies local settings and overrides the settings placed in Contentment.defaults.conf. A partial file is generated for you named Contentment.conf.sample. This will contain as much configuration that the build script is able to provide for you. You will still need to file in the details of database access and then save the file as Contentment.conf. Read Contentment.defaults.conf for a description of each of the options.

The log4perl.conf configuration file is for Log::Log4perl, so you should see that documentation for information on how to customize this configuraiton. Two different configurations are provided for you: log4perl.conf.screen and log4perl.conf.file. The log4perl.conf.screen version causes all log information to be dumped to the "STDERR" file handle. Under the Apache web server, this generally means that this will be dumped to the error_log. The log4perl.conf.file configuration is set to dump to the log file logs/contentment.log in the Contentment installation directory. This is my preference because the error_logs are too cluttered with Apache information already.

CGI CONFIGURATION

As of this release, Contentment is used via a CGI script only. In the future, there may also be other targets (the most likely target to be added is one for mod_perl). However, the CGI script may not be sufficient for your installation. For example, if you have your Perl libraries stored in a non-standard directory (as may be the case if you're running on a host that didn't have the module you needed so you installed it into your home directory), then you'll need to add extra directories to the Perl library search path.

Another reason you might want to do this is if Perl has been installed to a non-standard location. The CGI script assumes Perl can be found at /usr/bin/perl. However, Perl might actually be installed at /usr/local/bin/perl.

You may do this by either modifying handler.cgi directly (not recommended) or by creating a secondary script (recommended). The reason the latter is recommended is that if you choose to upgrade Contentment in the future, the install script will obliterate any custom changes to handler.cgi. Keeping them in a separate file will keep your changes safe.

An example script is provided in the cgi-bin directory named handler-path.cgi.sample. You may customize that file and rename it to handler-path.cgi. If you need custom library paths, replace the sample paths with yours. If you need to modify the location of Perl, you should change the very first line (the sh-bang line starting with "#!") to contain the name of the appropriate Perl program file.

You may also add to this file any additonal initialization or Perl code you want performed before the CGI handler is run. Do not run anything after the require "handler.cgi" line though. The CGI handler quits with a call to exit, so any code placed there will never run.

Finally, you'll need to adjust your web server configuration to use handler-path.cgi rather than handler.cgi.

WEB SERVER CONFIGURATION

This configuration is specific to Apache web server, the only web server this service has yet been tested upon. Here is an example configuration that should work. If you use Contentment with another web server, please let me know!

First, you will need to place an .htaccess file in the docroots/htdocs directory. A sample file has been included named htaccess.sample. For most installations, this file is fine as is and can just be renamed to .htaccess. Yet, you will need to edit it under at least the following two circumstances:

1. You have created a custom CGI wrapper for handler.cgi (described in the previous section).

2. The cgi-bin directory is not installed within docroots/htdocs.

3. You've installed Contentment outside of your Apache documentation root directory. (E.g., in a home directory for /~foo/)

In either case (and certainly others), you may wish to customize the .htaccess file.

CUSTOM HANDLER

If you are using a custom handler, the important lines are:

  RewriteRule "^$"    "cgi-bin/handler.cgi/index.html" [L]
  RewriteRule "(.*)$" "cgi-bin/handler.cgi/$1"         [L]

You'll want to replace the handler.cgi on both lines with the name of your handler (handler-path.cgi if you name it as suggested in the previous section).

RELOCATED CGI-BIN

If you've relocated cgi-bin, then you need to make sure the rewrite engine locates it properly. Here, the same two lines as above are important:

  RewriteRule "^$"    "cgi-bin/handler.cgi/index.html" [L]
  RewriteRule "(.*)$" "cgi-bin/handler.cgi/$1"         [L]

For example, if the URL to your Contentment site is:

  http://www.yourhost.com/contentment/

and the CGI script is at:

  http://www.yourhost.com/cgi-bin/handler.cgi

You want to add a "/" to the front of each of the two rules starting with "cgi-bin".

As another example, if the URL to your Contentment site is:

  http://www.yourhost.com/~foo/bar/Contentment/

and the CGI script is at:

  http://www.yourhost.com/~foo/htbin/Contentment/handler.cgi

You can replace "cgi-bin" in each line with "/~foo/htbin/Contentment".

RELOCATED HTDOCS

If the cgi-bin is still within the htdocs folder, but you've moved the htdocs folder to a place in a UserDir or an alias, then you can uncomment and modify the line:

  RewriteBase "/~foo/Contentment"

The replacement for /~foo/Contentment will be the URL needed to reach your installation.

It's installed in my UserDir at work, for example. The URL is:

  http://www.cis.ksu.edu/~sterling/

Thus, my RewriteBase line reads:

  RewriteBase "/~sterling"

That covers most of the basic situations. It's probable that someone will come up with something a bit more complicated. If you need help you can contact me at the email address below.

AUTHOR

Andrew Sterling Hanenkamp, <sterling@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is distributed under the same terms as Perl itself.

cpanm Contentment

perl -MCPAN -e shell
install Contentment