INSTALLATION ------------ ********************************************************************************* ********************************************************************************* ******** ******** WARNING! ACHTUNG! DANGER, WIL ROBINSON! ******** ******** This installation document is mostly superceded by the handy-dandy ******** interactive Q & A style installation that comes as part of the ******** Module::Build "Build.PL" script. Just the standard ******** ******** perl Build.PL && make && make test && make install ******** ******** so do the trick in these enlightened and civilized days. This ******** installation document has been kept so that you have a ghost of ******** a chance of fixing things if things go wrong, or of customizing ******** to your tastes. ******** ******** This document will be rewritten to reflect the new reality just ******** as soon as my order of Round To-Its comes in from the factory. ******** ********************************************************************************* ********************************************************************************* 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: http://www.cafweb.org/ The Examples.pod provides a good overview of how to develop applications using this framework. Required Core System Components =============================== * Unix-like operation system such as: + 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. * Perl programming language (v5.005+ needed, v5.8.4+ suggested) + 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. * Apache web server (v1.3 needed, v1.3.27+ recommended, v2+ supported for CGI operation but not for mod_perl operation) + http://httpd.apache.org/ * mod_perl module add-on to Apache web server (recommended) + Special installation section for this follows later in this document + http://perl.apache.org/ * Any database server that is supported by Class::DBI. The framework has been tested with: MySQL: http://www.mysql.com/ PostgreSQL: http://www.postgres.org/ SQLite (can be installed directly from CPAN) Others database systems may work. Deciding where to install the Examples ====================================== 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-bin directoy * The public webroot (e.g. htdocs or public_html) * Where you intend to install the "framework" directory. Installing CPAN =============== 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; Caveats / Notes --------------- * If the CPAN module is not currently installed on your system then go down to the instructions in the next section that tell you how to install it, do so, and then come back here. * If you like installing Perl modules by hand then go ahead and install all of them this way, but I don't recommend it; there are a LOT of modules. * If you regularly use something other than CPAN to install Perl modules on your system (for instance, CPANPLUS) then go ahead and use it, but I have to mention that I don't have any experience with those alternative module installation packages. * Your own operating system might provide a variety of Perl modules through its own packaging system. If you like you can install as many of those as you like before installing via CPAN. * Occasionally, the 'cpan' shell's installation technique crashes and burns when trying to install a given Perl module. This usually happens when the Perl module (or one of its Perl module dependencies) has a C language component to it and depends on having a certain set of C language libraries already installed on the system. If this happens then pay attention to the error output the CPAN shell tells you and then you've got to go digging to figure out how you can get that C language dependency on your system. (On Debian systems I recommend heavy use of http://packages.debian.org/. If you use something else then I'll have to trust you to know how to work with your own system best. Either way, you can always try emailing me for support. See the "Contact" information in this document.) You can use the CPAN shell to install any of the Perl modules hosted on the CPAN. Installation of CPAN module =========================== 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. Using CPAN to installing CGI::Application::Framework ==================================================== 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. Optional Database Modules ========================= 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: * install the database server * set up the database schema * configure CAF to use the database These are described in detail in the CGI::Application::Framework docs. Optional Modules ================ 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 "Apache::DBI" ------------- 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. "FreezeThaw" ------------ Not currently needed, but will be in future versions of the MVC kit. "Log::Dispatch" --------------- 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" -------------- 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. "DBI::shell" ------------ 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. Further Reading =============== 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.