$Id: INSTALL,v 1.3 2001/04/15 01:40:15 muhri Exp $

Table of Contents
-----------------
1. Prerequisites
  1.1 Gtk/Gnome
  1.2 Perl Modules
  1.3 Optional Software
  
2. Getting Started
  2.1 Upgrading
  2.2 Using the Installer
  2.3 Tarball vs. RPM Installation
  2.4 Manual Installation  
  2.5 Other Installation Methods
  
3. Database Configuration
  3.1 Supported Databases
  3.2 Installing DBI Drivers
  3.3 Creating the Database
  3.4 Selecting the Driver

4. Related Links
  4.1 Pronto Links
  4.2 Perl Links
  4.3 Database Links
  4.4 Gtk/Gnome Links
  4.5 RPM Links



1. Prerequisites

1.1 Gtk/Gnome

 Pronto requires Gtk version 1.2.3 or later.  If you are running a 
recent version of Gnome, you most likely already have a sufficiently
recent version of Gtk.  If not, you can get it from 
http://www.gnome.org/start/.

  If you want to build Pronto manually, you will also need the Gnome-Perl
bindings package (available from http://muhri.net/pronto/gnome-perl.tar.gz
or the Gnome CVS server). The Pronto Installer will automatically fetch
this package.


1.2 Perl Modules

Pronto requires the following Perl modules:

For CSV support:
	Text-CSV_XS-0.20
	SQL-Statement-0.1016
	DBD-CSV-0.1022

For PostgreSQL database support:
(message metadata only; the actual messages will be stored on disk):
    PostgreSQL 6.5.x or higher
    DBD-Pg-0.93

(storing message bodies in the database):
    PostgreSQL 7.1 or higher
    DBD-Pg-0.96

For MySQL/mSQL database support:
    DBD::mysql 1.2213
	(AKA Msql-Mysql-modules-1.2213)

Required for all databases (The ProntoInstaller.pl script will install 
these modules for you): 
    DBI-1.13
    DateManip-5.35
    MIME-Tools-4.124
    MIME-Types-0.02
    URI-1.05
    HTML-Parser-2.25
    Lingua-Ispell-0.07
    

 Although the IO::Socket module is part of the base Perl distribution 
as of version 5.004) some distributions fail to include it. You can check
to see if it is installed by typing

$ perl -MIO::Socket -e ''

 if you see something like
 
Can't locate IO/Socket.pm in @INC (@INC contains: 
/usr/lib/perl5/5.6.1/i686-linux 
/usr/lib/perl5/5.6.1 /usr/lib/perl5/site_perl/5.6.1/i686-linux 
/usr/lib/perl5/site_perl/5.6.1 /usr/lib/perl5/site_perl .).
BEGIN failed--compilation aborted.

 you need to install IO::Socket version 1.20 or higher.


1.3 Optional Software

 Pronto supports widgets that allow you to view your messages 
in an HTML window. Both the XmHTML widget (which is old and buggy),
and the new (still-under-development) GtkHTML widget are supported.

 For GtkXmHTML support, obtain the Gnome-Perl bindings package (see
section 4.4). Untar the package, change into the 
gnome-perl/GtkXmHTML/ directory and type:
 
$ perl Makefile.PL
$ make 
$ make install

 For GtkHTML support, install GtkHTML (From Gnome's cvs server).
Obtain the Gnome-Perl bindings package (see section 4.4). Untar 
the package, change into the gnome-perl/GtkHTML/ directory and 
type:

$ perl Makefile.PL
$ make
$ make install



2. Getting Started 

2.1 Upgrading

 If you are upgrading from an earlier version of Pronto, you really,
*really* should read the changelog at 

http://muhri.net/pronto/page.php3?node=ChangeLog

to see if any special actions are required. This software 
is rapidly evolving, and the database structure will occasionally
change.) Scripts for upgrading from older versions are available in 
/usr/lib/pronto/migration-scripts/. 

               *PLEASE* read the changelog!
               
               
2.2 Using the Installer.

 The best way to install Pronto is to use the ProntoInstaller.pl
script.  This script is included in both the RPM and the tarball, 
and is an all in one installation utility. ProntoInstaller.pl will 
fetch the latest stable version of Pronto automatically, so it is
should be all you need to install Pronto.

 The ProntoInstaller.pl script can be downloaded at
http://muhri.net/pronto/ProntoInstaller.txt (the script is named
with an extension of .txt to prevent the webserver from executing
the script). If you have the wget utility installed, you can
download the installer by typing

$ wget http://muhri.net/pronto/ProntoInstaller.txt

 Once you have downloaded the installer script, rename the file to 
ProntoInstaller.pl and make it executable:

$ mv ProntoInstaller.txt ProntoInstaller.pl
$ chmod +x ProntoInstaller.pl

 Then run the installer:

$ ./ProntoInstaller.pl

 Running the installer without passing any command line arguments 
will cause it to use wget for fetching files. If wget is not
installed on your system, don't panic; just pass the name and 
of another fetching utility and any required options as an argument:

$ ./ProntoInstaller.pl ncftpget 

 if your fetching utility requires options: 

$ ./ProntoInstaller.pl "ncftpget -f" 

 or

$ ./ProntoInstaller.pl "wget --proxy=someproxy --password=somepass" 


2.3 Tarball vs. RPM Installation

 The Pronto Installer allows you to choose between a tarball or RPM
based distribution. Not all of the required Perl modules are readily
available in the RPM format, so we must use tarballs for module 
installation.

 If you prefer that all of your software is installed as RPMS, you
must install RPMs of all required Perl modules referenced in section
1.2 *before* beginning the installation, else you risk having the
modules installed from tarballs anyway. You may have luck finding
RPMs for the modules at http://rpmfind.net/


2.4 Manual Installation

 We need to write something here. Until then, check out the Pronto
download page (see section 4.4) for more information about manual
installation.


2.5 Other Installation Methods

 Pronto .deb packages are available on the Pronto download page (see
section 4.1).
 
 

3. Database Configuration

3.1 Supported Databases

 Pronto can utilize many SQL databases to store information about 
your messages. Some databases also allow you to store the messages
in the database (as of this writing MySQL and PostgreSQL 7.1 are
known to support message storage in the database). See section 4.3,
Database Links, for links to download either of these databases.

 While PostgreSQL and MySQL are known to function properly with Pronto,
almost any relational database that has a driver for the Perl DBI 
should work. See section 4.3, Database Links, to check whether your 
preferred database has a driver. Note that if you choose to use a
database other than the ones mentioned, you may need to manually 
create the proper tables for Pronto to use. 

 Using an SQL database is highly recommended, as the CSV driver becomes 
very slow once you have more than a few hundred messages.


3.2 Installing DBI Drivers

 You must obtain and install the proper Perl DBI driver for your
database. DBD::Pg version 0.93 is required to use PostgreSQL with
Pronto, and DBD::Pg version 0.96 is required if you wish to store 
your messages in PostgreSQL. DBD::mysql version 1.2213 or higher 
is required for using MySQL with Pronto.

 The easiest way to install the driver is to use the CPAN 
module, by typing (as root):
 
# perl -MCPAN -eshell

(you may need to answer some configuration questions if this is your
first time using CPAN).

 Once in the CPAN prompt, type:
 
cpan> install (modulename)

 for example:
 
cpan> install DBD::Pg
or
cpan> install DBD::mysql

 and the CPAN module will download, compile, and install the newest
DBI driver for your database. If you wish to manually install the 
driver, the newest version can be found at 
http://www.cpan.org/modules/by-module/DBD/(module)-(version).tar.gz
(the driver tarball for MySQL is named Msql-Mysql-modules for 
historical reasons).


3.3 Creating the Database

 You must use PostgreSQL version 6.5 or higher in order to use your 
database with Pronto. Version 7.1 or higher is required if you wish
to store your messages in the database. See section 4.3, Database Links,
for links to download PostgreSQL sources and RPMS and installation 
information.

 MySQL version 3.22 or higher is recommended, but not required, for 
use with Pronto.

 Create a new database for each Pronto user, making the database 
name the same as the username. These users need not have any special 
privileges within the database engine, though they must have
sufficient permission to insert and delete records within their
own database.

 Replace all instances of <username> with the login name for the
instructions below.

For MySQL version 3.22 and higher, do the following:

# mysql -user=root mysql
(enter password)
mysql> create database <username>;
mysql> grant all privileges on <username>.* to <user>@localhost;
mysql> quit


For PostgreSQL version 6.5 and higher, do the following:

$ su - postgres
(enter password)
$ createuser <username>
Enter user's postgres ID or RETURN to use unix user ID:
(press return)
Is user "<username>" allowed to create databases (y/n) n (enter)
Is user "<username>" a superuser? (y/n) n (enter)
createuser: <username> was successfully added
Shall I create a database for "<username>" (y/n) y (enter)
$ exit


For PostgreSQL version 7.0.3 and higher, do the following:

$ su - postgres
(enter password)
$ createuser <username> --no-createdb --no-adduser 
CREATE USER
$ createdb <username>
CREATE DATABASE
$ exit


3.4 Selecting the Driver

 The first time Pronto is started, it prompts the user to select the
database driver to use. Select the appropriate driver for whatever
database you have installed. If you are not using a database, choose
the 'CSV' driver, ensuring that the required modules listed in section
1.2 under 'CSV support' are installed.



4 Related Links

4.1 Pronto Links 

 The Pronto home page can be found at:
http://muhri.net/pronto/page.php3?node=home

 The Pronto Installer is available for download at 
http://muhri.net/pronto/ProntoInstaller.txt

 The Pronto ChangeLog can be found at 
http://muhri.net/pronto/page.php3?node=ChangeLog

 The Pronto Download Page can be found at
http://muhri.net/pronto/page.php3?node=download


4.2 Perl Links

 All of the required Perl modules can be found by searching CPAN, the
Comprehensive Perl Archive Network at 
http://search.cpan.org

 To determine whether your preferred database has a Perl DBI driver,
check the DBI driver module listing at 
http://search.cpan.org/Catalog/Database_Interfaces/


4.3 Database Links

PostgreSQL

 PostgreSQL is available for download at
http://www.postgresql.org/sites.html 
 or
http://postgresql.readysetnet.com/sites.html

 PostgreSQL documentation can be viewed at
http://www.postgresql.org/users-lounge/docs/
 or
http://postgresql.readysetnet.com/users-lounge/docs/


MySQL

 MySQL is available for download at
http://www.mysql.com/downloads/index.html

 MySQL documentation can be viewed at
http://www.mysql.com/documentation/index.html


4.4 Gtk/Gnome Links

 The most recent version of Gnome (which includes Gtk) is available
for download at http://www.gnome.org/start/

 The most recent version of Gtk is available for download at
http://www.gtk.org/download/ 

 The Gnome CVS server

 The Gnome-Perl bindings package is available for download at
http://muhri.net/pronto/gnome-perl.tar.gz
or from the Gnome CVS server.

 
4.5 RPM Links

 There is an excellent search engine for RPM packages for many 
distributions available at http://rpmfind.net/