   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.

   The new WWWdb-Installer makes the installation easier as ever
   before!

   This examples are working on a SuSE 7.x 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 WWWdb tar-ball in the directory you want it, with:
   $ tar xvfz WWWdb-<Version>.tar.gz

   Switch to the new created directory:
   $ cd WWWdb-<Version>

   Untar the contrib tar-ball in this directory, with:
   $ tar xvfz WWWdb-contrib-<Version>.tar.gz

                     Run the WWWdb-installer
   $ perl INSTALL.pl

   Now you will be asked for some options. Normally it is ok to
   press <ENTER>. This uses the default, shown in square-brackets.

   Welcome to the WWWdb-Installer!
   We are going to install Version 0.8.2
          TO_INSTALL [MODULES,APACHE,WWWDB,DATABASE]:
            HOSTNAME [localhost]:
             DB_TYPE [Pg]:
             DB_NAME [wwwdb_0_8_2]:
             DB_HOST [localhost]:
             DB_USER [wwwrun]:
             DB_PASS []:

   Now the installation-process starts.
   It includes the following steps
     * Checking and installing the Perl-modules for WWWdb. They must
       be in tar.gz-archives in the contrib directory
     * Configuring and installing the apache-webserver for use with
       WWWdb. A translation-handler gets included, which transforms
       the WWWdb-URI's to a format, that WWWdb can handle.
     * Installing WWWdb and the corresponding modules
     * Create and load the database for WWWdb

   When the Perl-modules are installed, every module shows some
   messages. Some modules (like DBIx::Recordset) may need some
   user-input, but no special entries have to be done there.
   When the installation is finished the following messages come up:

   Installation of WWWdb (0.8.2) finished!
   Point your Browser to http://localhost/wwwdb to try it out!

   WWWdb accepts the following passwords:

   ------------+----------+--------------------------------------------
   Account     | Password | Description
   ------------+----------+--------------------------------------------
   anonymous   | wwwdb    | Anonymous englich user
   anonym      | wwwdb    | Anonymous german user
   wwwdb_admin | wwwdb    | WWWdb-Administrator
   ------------+----------+--------------------------------------------


--------------------------------------------------------------------------------

   MANUAL INSTALLATION

   If you want to install WWWdb by hand, the following steps are to do
   (after unpacking):


    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):
    $ echo "Include /etc/httpd/WWWdb.conf" >>/etc/httpd/httpd.conf
    $ cp Apache/WWWdb.conf /etc/httpd

    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/local/share/perl/5.6.1/Apache/WWWdb_TransUri.pm

    Now the apache-sever must be restarted:
    $ /etc/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
    - Re-create indices

    Here you can see all the call-options.
    $ InstallDB.pl -h
    Call:
    InstallDB.pl -D <database> -U <user>
    [-P <password>] [-H <host>]
    [-b Oracle|Pg|mysql|InterBase|ODBC]
    [-c][-e [-F <Field-List>] [-W <WHERE-clause>]][-i]
    [-s] [-dV]
    <xxx.dbdef> ... <xxx> ... <xxx.csv> ...

    Switches:
    -b <database-driver>
    at the moment, the following drivers are implemented:
    Pg        Postgres
    mysql     MySql
    Oracle    Oracle
    InterBase InterBase
    ODBC     Generic ODBC-driver

    -D     database
    -U     user
    -P     password
    -H     host (localhost)
    -F     list of fields to export, separated by comma
    -W     where-clause for export
    -s     silent-mode
    -d     Debugging-mode
    -I     Re-create indices (implies -c)
    -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' and it's
    db-password is 'dbpasswd')

    Create the tables for WWWdb and import the data:
    $ CreateNewDb.sh -cif -b pg -D test -U dbuser -P dbpasswd


    ConvertVersion.pl and it gets information of your database, and
    from which version you switch to what version.

    This is the calling syntax:

    $ ConvertVersion.pl -h
    Call:
    ConvertVersion.pl
    -D <database> -U <user>
    [-P <password>] [-H <host>]
    [-b Oracle|Pg|mysql|InterBase|ODBC]

    Switches:
    -b <database-driver>
    at the moment, the following drivers are implemented:
    Pg        Postgres
    mysql     MySql
    Oracle    Oracle
    InterBase InterBase
    ODBC     Generic ODBC-driver

    -D     database
    -U     user
    -P     password
    -H     host (localhost)

    -f <version>
    from which version to convert from (Format: x.y.z)
    -t <version>
    to which version to convert to (Format: x.y.z)

    Description:
    ConvertVersion.pl is used to upgrade the database-structures
    to the correct values of the actual version


    An example:
    If you want to upgrade your PostgreSQL database wwwdb for the database-user
    wwwdbuser from version 0.8.0 to 0.8.1 then you have to type:

    $ ConvertVersion.pl -b PG -D wwwdb -U wwwdbuser -f 0.8.0 -t 0.8.1

    The data will then be converted, your database is ready for use with
    WWWdb 0.8.1.

                             --- Attention! ---

    Never forget to backup your complete database before converting any data!


    Prepare your Perl-Distribution

    Here on my 'clean' SuSE 7.0 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 and/or
    3.DBD-InterBase - DBI-Driver for  InterBase and/or
    4.Msql-Mysql-modules - DBI-Driver for MySql and/or
    5.DBD-ODBC - DBI-Driver for ODBC
    6.DBI - The Database-Interface
    7.DBIx-Recordset - The basic mechanism for db-access
    8.HTML-Parser - HTML en-/decryption
    9.HTML-Tagset - Database for HTML-tags
    10.HTML-Template - Templates fpr HTML-code
    11.Carp-Assert - Security-assertions for development
    12.Digest-MD5 - creating of unique Hashes
    13.DelimMatch - Scan Expressions ober more than one line
    14.Locale-PGetText - i18n-Handling
    15.Date-Calc - Calculation with Dates

    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
