=pod

=head1 NAME

OpenFrame::Install - OpenFrame installation guide

=head1 DESCRIPTION

C<OpenFrame> consists of a suite of Perl modules. C<OpenFrame> has
many dependencies on other Perl modules which are available on the
CPAN. It is typically used to serve web applications, and comes with
two mechanisms to achieve this: a stand-alone web server
(C<OpenFrame::Server::HTTP>) and a plugin to Apache via mod_perl
(C<OpenFrame::Server::Apache>). The rest of this document goes into
detail about how to install C<OpenFrame>.

=head1 PERL MODULE INSTALLATION

C<OpenFrame> is available from the CPAN. Due to the large number of
dependencies C<OpenFrame> requires, it is recommended that you install
it via the CPAN shell:

  # perl -MCPAN -e shell
  cpan shell -- CPAN exploration and modules installation (v1.59)
  ReadLine support enabled
  
  cpan> install OpenFrame
  ...

The CPAN shell will figure out all the dependencies and install the
required modules for you before it installs C<OpenFrame>, which is
terribly handy.

The most notable dependency is C<Apache::SessionX>, which provides the
back-end of the session handling in OpenFrame (but is badly named, as
it does not require Apache). It is somewhat tricky to install as it
asks important questions. You must choose a session storage, which is
then used for all C<OpenFrame> sessions. We suggest picking the
"FileFile" storage. First create a directory for the sessions, such as
/tmp/sessions/ - also create /tmp/sessions/locks/. Then during the
C<Apache::SessionX> installation process, say "n" to every storage
other that "FileFile" and then set LockDirectory to
"/tmp/sessionx/locks/" and Directory to "/tmp/sessionx/". The tests
should succeed (make sure you have created the directories!). You may
wish to clean up the files in the directories after installation.

However, if you wish to install it by hand (or if you have downloaded
the latest development version from CVS), simply do the following
inside the C<OpenFrame> directory:

  % perl Makefile.PL
  % make
  % make test
  % make install

If you want to put OpenFrame in a specific directory, then append
C<PREFIX=E<lt>pathE<gt>> to the C<perl Makefile.PL> command.

C<OpenFrame> comes with a fairly comprehensive test suite (run during
the "make test" phase") which checks that everything is properly
installed and working. If you get errors during the test phase, it is
most likely due to C<Apache::SessionX> problems, so check its
configuration and directory permissions.

=head1 RUNNING THE EXAMPLES

Once you have installed the C<OpenFrame> Perl modules, you are all set
to run the examples. The examples all use the stand-alone HTTP server,
so you do not need to run or configure Apache to run them. All the
examples are in the "examples" directory in the C<OpenFrame>
distribution.

The simplest example is the webserver example. Change into the
"webserver" directory and run "webserver.pl":

  % cd examples
  % cd webserver
  % ./webserver.pl 
  Point your browser to http://localhost:8000/ to see the website!

If you follow the instructions and point your web browser at the URL
http://localhost:8000/ you will see a simple website. It may be
instructive to read the contents of "webserver.pl" to attempt to
understand what is going on. Press CONTROL-C to stop running the web
server.

A slightly more complicated, but much more fun, example is the hangman
example:

  % cd ..
  % cd hangman
  % ./hangman.pl
  Point your browser to http://localhost:8000/ to play hangman!

You can now play hangman with your web browser! Read "hangman.pl" and
"Hangman/Application.pm" and "Hangman/Generator.pm". The hangman2
example shows a cleaner separation of content and presentation.

There are various other examples in the examples/ directory.

=head1 INSTALLATION WITH APACHE

While using the stand-alone HTTP server (as the examples do) is fine
for testing and low usage, for production use we recommend setting
C<OpenFrame> up with Apache and mod_perl.

C<OpenFrame> should be fairly simple to install for anybody who is
familiar with C<Perl> and more specifically, C<mod_perl>.

=over 4

=item Configuration

To configure OpenFrame for the first time, simply execute the
configbuilder script.  This will place a file in your current
directory called .openframe.conf.  Edit the values in this file as you
see fit.  Note: for system wide config you probably want to put that
file in /etc/openframe.conf

=item Web Server Plug in

Simply install the handler for your server.  In the case of Apache
it's C<OpenFrame::Server::Apache.> We map an entire server to the one
handler.  You could have multiple copies of OpenFrame running, but
it's not a tested configuration.

Our configuration looks similar to:

  <VirtualHost [SOME.IP.ADDRESS]>
        ServerName      [Some Server Name]
        Port            80
        DocumentRoot    [Some Directory]
        <Directory [Some Directory>
                Options -Indexes -ExecCGI -FollowSymLinks -Includes
        </Directory>
        <Location / >
                SetHandler      perl-script
                <Perl>
		  # this is only needed if you use a PREFIX.
                  use lib '/path/to/install/dir/lib/site_perl'; 
                </Perl>
                PerlHandler     OpenFrame::Server::Apache
        </Location>
  </VirtualHost>

Of course you need to edit some of those values to get any real
mileage from the software, but you should have the general idea.

=back

=cut
