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.