NAME
    OpenFrame::Install - OpenFrame installation guide

DESCRIPTION
    `OpenFrame' consists of a suite of Perl modules. `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
    (`OpenFrame::Server::HTTP') and a plugin to Apache via mod_perl
    (`OpenFrame::Server::Apache'). The rest of this document goes into
    detail about how to install `OpenFrame'.

PERL MODULE INSTALLATION
    `OpenFrame' is available from the CPAN. Due to the large number of
    dependencies `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 `OpenFrame', which is
    terribly handy.

    The most notable dependency is `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 `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
    `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 `OpenFrame' directory:

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

    If you want to put OpenFrame in a specific directory, then append
    `PREFIX=<path>' to the `perl Makefile.PL' command.

    `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 `Apache::SessionX' problems, so check its configuration and
    directory permissions.

RUNNING THE EXAMPLES
    Once you have installed the `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 `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.

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
    `OpenFrame' up with Apache and mod_perl.

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

    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

    Web Server Plug in
        Simply install the handler for your server. In the case of Apache
        it's `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.

