This document describes the procedure for the installing the CGI::Application::Framework (CAF), a fully-featured web application development platform built on CGI::Application.
The other documentation is in POD format:
CGI::Application::Framework - general docs Examples.pod - guide to the Example apps
You can read these documents online in HTML format by visiting:
http://search.cpan.org/dist/CGI-Application-Framework/lib/CGI/Application/Framework.pm
The docs are also available onlin at the CAF web site:
The Examples.pod provides a good overview of how to develop applications using this framework.
+ Solaris
+ Linux (e.g. Red Hat Linux 9, SuSE Linux, Debian GNU/Linux)
(E.g. Debian GNU/Linux 'unstable' was used in the creation of the
system and in producing its documentation.) Conceivably the
framework could be installed on a Windows-based system with some
extra work but this hasn't been attempted yet.
+ Test to see what you have installed on your system first
with:
$ which perl
If this yields a Perl on your $PATH (e.g. /usr/bin/perl or
/usr/local/bin/perl) then follow this up with
$ perl -v
to see which version your $PATH perl is.
+ Special installation section for this follows later in this
document
+ http://perl.apache.org/
MySQL: http://www.mysql.com/
PostgreSQL: http://www.postgres.org/
SQLite (can be installed directly from CPAN)
Others database systems may work.
If you choose to install the example applications, you will need to be running a local webserver such as Apache.
You can install the Example applications into your existing web space, or you can install them into a new virtual host. There is also a portion of the application (the "framework" directory) that should be installed outside of your web space.
Before you install you will need to know the locations of the following with respect to your web server:
The CGI::Application::Framework is based on the Perl programming language and makes use of a great number of existing Perl modules, primarily CGI::Application. These modules are collected on the CPAN (Comprehensive Perl Repository Network), the standard collection of Perl resources.
The easiest way to install CGI::Application::Framework and all of the modules it depends on is to install and run the CPAN module on your Perl system. Many operating systems already have the CPAN module installed. To check to see if this is the case, first try:
$ su -
# which cpan
This might yield /usr/bin/cpan or /usr/local/bin/cpan. Note that I recommend you "su -" to become root because the $PATH of root might be different from your own regular user's $PATH, and as you need to be root in order to install CPAN modules properly you may as well act as root when you check for the existance of the 'cpan' executable script.
It is possible that the CPAN module is installed even "which cpan" does not show a 'cpan' executable script in your $PATH. Here is another way to test for its presence:
# perl -MCPAN -e 'print "$CPAN::VERSION\n"';
Now, you will invoke the interactive CPAN shell in order to install the needed modules. (Make sure you are still root.) If "which cpan" showed a result then type
# cpan
If not, then use:
# perl -MCPAN -e shell;
You can use the CPAN shell to install any of the Perl modules hosted on the CPAN.
If you don't already have the CPAN module installed on your computer, you can get it from the web at:
http://www.cpan.org/modules/by-module/CPAN/
In this directory you will find a file called CPAN-1.xx.tar.gz; for example:
http://www.cpan.org/modules/by-module/CPAN/CPAN-1.76.tar.gz
Download the most recent (that is, highest numerical value) of this file. Install this Perl module using the established procedure for installing Perl modules:
$ tar xzvf CPAN-1.xx.tar.gz
$ cd CPAN-1.xx
$ perl Makefile.PL
$ make
$ make test
$ su -
# make install
The first time you run the interactive 'cpan' shell (using either of the methods described earlier) you will be presented with a list of questions that are needed to configure your CPAN installation. How to answer these should be mostly self-evident. More information about the CPAN module and its configuration can be found at http://search.cpan.org/~andk/CPAN/lib/CPAN.pm. I recommend that you answer "follow" to the question that asks you for your policy on building prerequisites.
From within the CPAN shell type:
install CGI::Application::Framework
The CGI::Application::Framework depends on a large number of modules. CPAN will install them for you.
After the prerequisites are installed and the CGI::Application::Framework installer starts running, you will be asked a series of questions to let the installer know where you want the Example applications to be installed.
CGI::Application::Framework supports multiple database types. The example applications use sqlite, which allows them to run in an environment that doesn't have a webserver installed.
Any of the following are supported:
DBD::mysql - driver for the MySQL database DBD::Pg - driver for the PostgreSQL database
Other databases (Oracle, Sybase, DB2, MSSQL, ODBC) should work, but have not been tested with the CAF.
In order to get a new database working with the CAF, you will have to do the following three things:
These are described in detail in the CGI::Application::Framework docs.
Here are 5 more modules you might want to install now, but it is not necessary.
Apache::DBI
FreezeThaw
Log::Dispatch
Devel::ptkdb
DBI::Shell
If you plan on using this kit under a mod_perl environment then this will create persistent database connections and a database connection pool for you, speeding up your application considerably.
Not currently needed, but will be in future versions of the MVC kit.
Not currently needed, but might be in future versions. Also, you might want to use it to enhance your own Log::Log4perl usage.
Devel::ptkdb is the Tk debugger for Perl, which is a graphical user interface for Perl debugging. It's quite nice! This is not required for the functioning of the MVC framework but it is very handy for Perl application debugging, including CGI-based Perl application debugging. (But not ones run through Apache::Registry.) When you try to install this via the CPAN module you have to make sure that your root account has permission to access the X display. For instance, from the non-root account that owns your X session, type "xhost +", copy the .Xauthority file from the home directory of the non-root user who owns the X session to /root, and make sure that your root user has the correct DISPLAY environment variable. Information regarding how to use Devel::ptkdb in a CGI run of an MVC framework program is found in the GETTING_STARTED.txt document, and you can see it in action in the various ".cgi" versions of the .pl web application scripts included in this distribution.
Useful for opening a command prompt to the SQLite database which doesn't have its own command prompt. This is used to load an SQLite database with seed data. See the sql/mvc_example.sqlite file for details.
The framework and its example applications are now installed. Proceed to the Examples.pod document and the POD-format docs within CGI::Application::Framework itself to learn how to understand the example applications and how to create your own.