                       How to install WWWdb
                       ====================


                       General information

WWWdb is in a beta state. This means, that tons of ideas are waiting to
be implemented, not that the software isn't stable. Of course, there are
some bugs in, but you should run it stable on your system, as we do.

Because of the beta state, bigger changes in the config-file could be
expected. So I plan for the future, to store all informations in the
database. Of course, there will be tools which do the conversion! Also
no automated installation-process is available yet, but in the future it will
come. :-)

This examples are working on a SuSE 6.2 Distribution with apache
installed in the /usr/local/httpd-hierarchy.
NOTE:
Every Line prefixed with a '$' shows you, what to type for doing this
installation-step. The installation works as follows:


                        Unpack WWWdb

Untar the tar-ball in the directory you want it, (by example
/usr/local/lib) with:
$ tar xvfz WWWdb-<Version>.tar.gz
Switch to the new created directory:
$ cd WWWdb-<Version>


           Set up the web-server to work with WWWdb

Configure the Apache-Server (if you haven't done this with a previous
version of WWWdb):

      must be compiled and installed with perl_mod
      make apache recognize URIs of the form:
      http://localhost/WWWdb/<Session-Id>/<Database>/<Config-file>

This steps must be done as root (and do not forget to use >> for
redirection, else your httpd-config-file gets killed):
$ cat ApacheConfig.addon >>/etc/httpd/httpd.conf
Now the pointer to your Address-translation-handler is installed. Of
course the handler itself must be installed. On my System it's done with:
$ cp WWWdb_TransUri.pm
/usr/lib/perl5/site_perl/5.005/i586-linux/Apache
Now the apache-sever must be restarted:
$ /sbin/init.d/apache restart
If no error-messages appear, apache should be working correct now.


                    Now we install WWWdb ...

Install the script WWWdb.cgi:
$ cp WWWdb.cgi /usr/local/httpd/cgi-bin
Install the WWWdb-data-directory (here with a symbolic link)
$ ln -sf `pwd` /usr/local/httpd/htdocs/WWWdb
Create and set the right permissions for the tmp-directory
$ mkdir tmp
$ chmod 777 tmp
Set your hostname in lib/WWWdb/Pre.rc
$ vi lib/WWWdb/Pre.rc


                     Prepare your Database

Set your db-name etc in lib/WWWdb/Db/<Db>.rc
$ vi lib/WWWdb/Db/<Db>.rc

Create links for the db-dummys '' and Default.
$ ln -sf lib/WWWdb/Db/<Db>.rc lib/WWWdb/Db/.rc
$ ln -sf lib/WWWdb/Db/<Db>.rc lib/WWWdb/Db/Default.rc
$ ln -sf lib/WWWdb/Db/<Db>.pl lib/WWWdb/Db/.pl
$ ln -sf lib/WWWdb/Db/<Db>.pl lib/WWWdb/Db/Default.pl

Now, you need to setup the database. The script CreateNewDb.sh calls the
script InstallDB.pl, which can:

     Create a Table, using the .dbdef-file
     Import Data, using the .csv-file
     Export Data, using the Table-name

Here you can see all the call-options.
$ InstallDb.pl -h
        InstallDB.pl -d <System-ID>:<User>[/<Password>][@Host>]
            [-b Oracle|Pg|CSV] [-c][-e][-i]  [-s] [-DV]
            <xxx.dbdef> ... <xxx> ... <xxx.csv> ...

    Switches:
        -b <database-driver>
               at the moment, the following drivers are implemented:
               csv       Comma-Separated-Values
               pg        Postgres
               mysql     MySql
               oracle    Oracle
        -d <System-ID>:<User>[/<Password>[@<Host>]]
               Login-info for the database
        -s     silent-mode
        -D     Debugging-mode
        -V     show version
        -f     force operation
        -c     create tables (*.dbdef)
        -e     export tables (*)
        -i     import tables (*.csv)

    Description:
        InstallDB.pl is used to create, import and export
        database-tables.

Now switch to the Database-Directory:
$ cd <WWWdb>/lib/WWWdb/Db

Create your new database as usually (look in the database-manual)

(Now we are assuming that the database is of type PostgreSQL and it's
name is 'test', and the db-user is 'dbuser')

Create the tables for WWWdb and import the data:
$ CreateNewDb.sh -cif -b pg -d"test:dbuser"



                 Prepare your Perl-Distribution

Here on my 'clean' SuSE 6.2 Distribution, the following perl-modules
must be added (in this sequence):

1. DBD-Oracle - DBI-Driver for Oracle and/or
2. DBD-Pg - DBI-Driver for PostgreSQL
3. Msql-Mysql-modules - DBI-Driver for MySql
4. DBI - The Database-Interface
5. DBIx::Recordset - The basic mechanism for db-access
6. IniConf - Parsing of config-files
7. HTML-Parser - HTML en-/decryption
8. Carp-Assert - Security-assertions for development
9. Digest-MD5 - creating of unique Hashes

To make it easier to install this modules, they are packed in the
./contrib-subtree.

The installation-process is easy:
$ tar xvfz <Module>.tar.gz
$ cd <Module>
$ perl Makefile.PL
$ make
$ make test # if you want
$ make install # as root
If you use some datatypes like date etc., you have also to replace some
perl-modules, until my patched versions get included into the
distributions.

On my sytem the following commands are neccesary (as root):
$ cp contrib/Oracle.pm
/usr/lib/perl5/site_perl/5.005/i586-linux/DBD
$ cp contrib/Compat.pm /usr/lib/perl5/site_perl/5.005/DBIx
$ cp contrib/Recordset.pm /usr/lib/perl5/site_perl/5.005/DBIx

Enter the url http://<hostname>/wwwdb and enjoy !!!!

If you have any troubles, please feel free to contact me at Klaus@twc.de
or visit our bugtracker at http://www.twc.de/jitterbug


                        ... now it's done!!
