$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/
