# $Header: /cvsroot/cascade/cascade/INSTALL,v 1.24 2001/09/30 02:32:17 markjugg Exp $

NOTE: please read RELEASE_NOTES first to discover important features
and limitations in this version. 

################
THE QUICK START
----------------
( This assumes that all the system requirements from below are already
installed, and that you have some familiarity with Unix and Perl)

For Postgres users
======================================
* psql -c 'create database "cascade"'; # Although other database names
  work equally well. 

* personalize the entry in the bottom of create_all.sql for yourself.
   This is creating the base account for the administrator. 

* psql -d cascade -f sql/create_all.sql  [-h yourdbserver.com] [-u]

For Mysql users
=====================================
* mysqladmin create cascadedb
  As with postgres, other database names will work equally well, "cascade"
  appears to be a reserved word, and does not create successfully

* personalize the entry in the bottom of create_all_mysql.sql for yourself.
  This is creating the base account for the administrator. 
  
* install the tables using
  mysql cascadedb < sql/create_all_mysql.sql

For all users
=========================================
* edit config/config.pl to taste. 

* In the above file you'll define the location the main script,
  $CFG{CASCADE_CGI} . To log in as adminstrator to start adding
  categories and items, visit $CFG{CASCADE_CGI}/login
  You will be redirected for registration. Use the email address and password
  that you entered above in create_all.sql

#########################################
THE LONG AND COMPREHENSIVE INSTALL NOTES
-----------------------------------------

0. INTRODUCTION

Cascade is a web-based system to manage an index of resources,
like your own little Yahoo! It takes basic familiarity with 
Unix, Perl, Postgres and Apache to get it installed and
configured. However, it takes no technical skill to run
once it's set up. 

1. SYSTEM REQUIREMENTS

You definitely need all these components. These are the earliest
versions of these modules that I have tested with the current
system. I know it depends some newer features in CGI.pm, DBI.pm,
DBIx::Abstract and Postgres 7.1. Earlier versions of the other
compotents are likely to be compatible.

* Apache 1.3.14 [ http://www.apache.org ] (other webservers may work) 
* Postgres 7.1  [ http://www.postgresql.org ] or MySQL 3.23.40 [ http://www.mysql.org ]
* Perl 5.005_03 

Perl modules:
	* DBD::Pg 1.00 or DBD::mysql 2.0902
	* CGI::Application 2.0
	* CGI.pm 2.75
	* DBI.pm 1.18
	* Digest::SHA1 1.03 
	* HTML::Template.pm 2.2
	* HTML::FillInForm .18
	* Data::FormValidator 1.5 
	* DBIx::Abstract .97

If you have root access, you can install all the needed perl modules,
which the exception of DBD::Pg or DBD::mysql, by installing
Bundle::Cascade. As root, you can simply do this like this:

perl -MCPAN -e 'install Bundle::Cascade';

Read this next section if you don't have root access:

    * Create the directory to store your CPAN/MyConfig file in.
        $ mkdir -p ~user/.cpan/CPAN

    * Locate the primary CPAN Config file and make a personal copy
    of it.
        $ perldoc -m CPAN::Config >~user/.cpan/CPAN/MyConfig.pm

    * Set an environment variable for CPAN.pm knows where to find
    your personal module modules.
             # this way to set an environment variable may be specific
             # to the bash shell-- there's probably a more portable way to do it.
             $ export PERL5LIB=~user/perllib

    * Edit your MyConfig.pm file. Here is an example of a minimal
    set of changes which may be sufficient for most people. For details on
    the format of this file, refer to perldoc CPAN.pm
          'build_dir' => q[~user/.cpan/build],
          'cpan_home' => q[~user/.cpan],
          'keep_source_where' => q[~user/.cpan/sources],
          'makepl_arg' => q[LIB=/home/user/perllib
                       INSTALLMAN1DIR=/home/user/man/man1
                       INSTALLMAN3DIR=/home/user/man/man3 
                       INSTALLBIN=/home/user/bin
                       INSTALLSCRIPT=/home/user/scripts], 

    * You are now ready to try installing modules through the usual
    CPAN.pm methods. A simple example would be:
                perl -MCPAN -e 'install Bundle::Cascade' 

For more documentation on installing Perl modules, try these
resources:
	perldoc CPAN
	perldoc perlmodinstall
	http://theoryx5.uwinnipeg.ca/CPAN/perl/pod/perlmodinstall.html

2. DATABASE CREATION

Everyone
--------

You can either put Cascade in it's own database, or add the needed
tables to an existing database. They all start with the prefix "cas_"
to avoid name clashes with existing tables.

If something goes wrong there are SQL scripts to totally remove your
cascade tables so you can start from scratch again (drop_all.sql for
Postgres and drop_all_mysql.sql for MySQL. 

Postgres Users
--------------

The easiest way to do this
is to connect to Postgres using psql and issue the command 'create
database yourdatabasename'. Notice that if you want to be clever and
name your database 'cascade', you'll need to put quotes around it like
this: ' create database "cascade"; ' since cascade is a reserved word.

If Postgres returns an error at this stage, consider consulting the
official Postgres documentation: http://www.postgresql.org/idocs

MySQL Users
-----------

# XXX To be written, including an explanation of what to do if this
# happens: 
mark@asana cascade> mysqladmin create cascadedb
mysqladmin: create of 'cascadedb' failed
error: 'Access denied for user: '@localhost' to database 'cascadedb''
mark@asana cascade>

Perhaps include something like:
If MySQL returns an error at this stage, consider consulting the
official MySQL documentation:
http://www.mysql.com/doc/

3. WEBSERVER CONFIGURATION

Permissions

make sure that the CGI scripts are in a directory authorized to
execute CGI scripts, and that permissions are set correctly. To use
the ability of the software to write static pages, the webserver will
need write permissions on the directory you've defined in 
$CFG{HTML_ROOT_ROOT}. Unless you are using a system like Apache's SuExec system,
this usually means making this directory "world writeable". You should
be aware of the security implications of making a directory world
writeable before using this feature. 
 
Includes

Cascade makes use of Apache's server side include system for static
version of the pages it creates. The feature is not required either,
rather the include files created are a convenience to allow you to
easily integrate Cascase with other static content on your
website. There will be more documentation on this available
eventually. If this is isn't already enabled, you'll need to add
"Includes" or "IncludesNOEXEC" to the Apache "Options" directive. More
documentation on this is available here:
http://www.apache.org/docs/mod/core.html#options

4. SOFTWARE CONFIGURATION

Follow the comments in config/config.pl to configure the
software to your taste. 

5. TESTING and USAGE

If all goes well, you should be able to visit
$CFG{CGI_ROOT_URL}/login
in a browser and see some options to add
items and categories. If you choose an option to "write static pages"
and your permissions are set correctly, those should appear below
$CFG{HTML_ROOT_URL}.

There are a few helpful files that are generated automatically when
you write the static pages that are useful for maintaining other
static content as a part of this system. For example, if one your
resources you point to is an article on the same website. This made to
be used in conjunction with Apache Server Side Includes.

These are:

includes/footer.html
includes/header.html

These reflect the contents of footer.tmpl and header.tmpl from your
templates directory  
	
In each category, 2 files are created for SSIs:
   dir_links.html - This is a list of links to other resources in the same category
   dir_url.html - This is a formatted URL of the current category. 
	

6. TEMPLATE CUSTOMIZATION

You can customize the how the site looks by modifying some HTML files
located in templates/en/basic/. There you'll see a number of variables
hidden in HTML comments. Besides moving them around and taking some
out, you can also do a bit more by reading the documention for
HTML::Template here:
http://support.summersault.com/perldoc/HTML-Template.html#The_Tags
You can also safely add any of the %CFG variables from config.pl by
using the prefix "cfg_" on the variable name name like:
<!-- tmpl_var name=cfg_system_name -->

Be aware that Dreamweaver and other editors "mess with" these tags
when you edit the HTML. Make backups first!

This is intended to be a English-based "basic" template style. If you create
a set of templates that you would like to share with others, please contact me: mark@summersault.com 

7. FEEDBACK

That's all for now! I still have a long way to go with documentation +
adding new features. Feel free to email me with questions, suggestions and comments.

For questions regarding internationalization contact melero@eurolands.com
For questions regarding MySQL support contact simon@iseek.ws

Thanks!

   -mark
   mark@summersault.com
