Horde Database Installation Guide
Copyright 1999 Ivan E. Moore II <rkrusty@tdyc.com>
Copyright 1999 Mike Hardy <mikeh@spark.com>
Copyright 2000 Chuck Hagenbuch <chuck@horde.org>
Copyright 2000 Brent J. Nordquist <bjn@horde.org>

This code is licensed under the GNU Public License.
See the file COPYING in the main directory.

$Author: bjn $
$Revision: 1.1.2.9 $
$Date: 2000/09/09 02:44:43 $


----
NOTE
----

There are database-specific readme-type files, along with the scripts
mentioned below, in horde/scripts/database/.  [Note 06/27/2000 by BJN:
However, the db-specific READMEs are being merged into this file, and
will eventually be obsolete.  For MySQL, this file is the one you want.]


--------------------
Purpose of this file
--------------------

What this file will hopefully do for you is make setting up
your database for use with Horde much easier.  The goal
is not to help you setup your database for general use, just
how to setup the tables and users for Horde.


----------------------
Requirements for Horde
----------------------

Horde uses PHPLib to handle its database management.  If 
PHPLib supports your database of choice most likely it will
work with Horde.  Currently we know for sure that Horde works
with:

   MySQL
   PostgreSQL
   Oracle
   Sybase
   Informix

MySQL was the original database supported by Horde and should at all
times (most likely) work for sure.  PostgreSQL I can verify works
like a champ.  The others are more recent additions or those that
have less support currently.  For this reason (and the reason
that I cannot verify personally that they work or have ever
configured them) they won't be mentioned much in this file.
No one using Informix has contacted us for a while, but Oracle and 
Sybase are both currently used and should work.

You will need to have your database preconfigured and working
on your system before you even get to this stage.  For help
with this please consult your database specific help files.


---------------------------
Database Name/User/Password
---------------------------

Please NOTE that the database configuration steps listed below MUST
match what is configured within Horde/IMP.

Specifically, if you change the database name, user, or password while
configuring the database (below), you will need to make the same changes
to your imp/config/defaults.php3 and phplib/local.inc files as well.

See also the horde/scripts/database/dbpasswd.sh script which can be used
to change the database password in all required locations.


-----------------------
Methods of Installation
-----------------------

There are 2 basic methods for configuring your database. The
first is manually doing it yourself. This is the method
that will make sure that things are setup as you can see 
step by step that things are being configured properly.

The other method is to use one of the scripts that have been
created to automatically configure your database.  These
scripts should work but there are times when things may not
work the way they are supposed to.  Also, when using scripts
you need to be aware that they may not be setup exactly
for your system so you need to verify them to make sure things
are correct for your particular install before using them.


=-=-=-=-=-=-=-=
MANUAL INSTALL:
=-=-=-=-=-=-=-=

For the 1.2.x version of Horde you will need to install the 
PHPLib session tables.  We have included the create scripts for
PostgreSQL and MySQL.  You can find them in horde/scripts/database.
If you are using a different type of database, please check your
PHPLib distribution for the proper creation scripts.  

Your database name needs to be 'horde'.  Insert the PHPLib 
session tables into your newly created 'horde' database.  If you
look through the creation scripts, you'll notice there are tables
for auth_user and auth_user_md5.  We are currently not using these
tables but are slowing working them in so it's a good idea to
insert them as well. 

Here is a breakdown of the tables and their elements:

Table 1:

   active_sessions (
      sid         varchar(32) not null,
      name        varchar(32) not null,
      val         text,
      changed     varchar(14) not null,
      primary key (name, sid),
      key changed (changed)
   )

Table 2:

   imp_addr (
      user        varchar(120) not null,
      address     varchar(120) not null,
      nickname    varchar(255),
      fullname    varchar(255),
      primary key (user, address)
   )

Table 3:

   imp_pref (
      user        varchar(255) not null primary key,
      fullname    varchar(70),
      replyto     varchar(70),
      lang        varchar(30),
      sig         text
   )

I kind of broke them down as they would go into the database...ie, the
name then what it is...(example:  val is a text field).

The database name itself needs to be "horde" and needs to be created.

Next you'll need to create a user or give a user access to this
database. This user will need pretty much full control over this
database. The username we suggest is "hordemgr".

Here are a few configuration tips for MySQL and PostgreSQL:

---------------------
MySQL Manual Install:
---------------------

*** NOTE ***

The script (horde/scripts/database/mysql_create.sql) does the following
steps so you wouldn't have to retype them.  See the SCRIPTED INSTALL
section, below.

These commands will setup a user called hordemgr with a password of
'hordemgr' and give it access to the horde database:

    mysql -u root -p mysql
       mysql> create database horde;
       mysql> insert into user (host, user, password) values ('localhost', 'hordemgr', password('hordemgr'));
       mysql> insert into db values ('localhost', 'horde', 'hordemgr', 'y', 'y', 'y', 'y', 'y', 'y');
       mysql> flush privileges;
       mysql> quit

After setting up your tables in MySQL you need to run this command:

    mysqladmin -u root -p reload

--------------------------
PostgreSQL Manual Install:
--------------------------

insert into pg_shadow (usename, usesysid, usecreatedb, usetrace, usesuper, \
       usecatupd, passwd) values ('hordemgr', '33', 't', 't', 't', 't', \
       'hordemgr') ;

   This will create a postgres user called hordemgr who will be connecting
to the database as the user who's userid is 33 (on Debian, apache is ran
as user www-data which uses the userid of 33, this will be nobody on other
systems.).  This user also has the password of 'hordemgr'.

GRANT SELECT, INSERT, UPDATE ON active_sessions, auth_user, auth_user_md5 TO hordemgr;

  This will give the user hordemgr access to these tables (active_sessions, 
etc...).  

Also, you need to make sure you allow TCP connections into your 
database.  PostgreSQL has a switch in one of its configuration files
(postmaster.init on Debian) that needs to be set to yes:

PGALLOWTCPIP=yes

Without this set to yes Horde won't be able to talk to your database and
you'll get tons of errors. :)

That's about it.  You need to restart your database just to make sure
everything starts up the way it should.


=-=-=-=-=-=-=-=-=
SCRIPTED INSTALL:
=-=-=-=-=-=-=-=-=

(NOTE: Scripts are located in horde/scripts/database/)

The easier way of configuring your database is to use one of the
scripts that have been made available to you.  Here is a breakdown
of how to use each script.

-----------------------
MySQL Scripted Install:
-----------------------

MySQL's script is called mysql_create.sql.  Please look it over to make
sure that any system specific settings (or personal choices) are set to
your desired settings...ie usernames, etc...

Then run the script to create the Horde user and tables (you will be
prompted for the MySQL root password):

   mysql -u root -p < mysql_create.sql

You then need to do a "reload":

   mysqladmin -u root -p reload

----------------------------
PostgreSQL Scripted Install:
----------------------------

PostgreSQL's script is called pgsql_create.sql.  Please look it over
to make sure that any system specific settings (or personal choices)
are set to your desired settings...ie usernames, etc...

Then run the script to create the Horde user and tables:

  su - postgres  (or whoever your database runs as..usually postgres)

  psql template1 < pgsql_create.sql

That's it, restart PostgreSQL and try it out.


=-=-=-=
NOTES:
=-=-=-=

This is by far not a complete HOWTO. This is just a compiled list of what
people have contributed so far. Some of this is from my personal experience
(MySQL and PostgreSQL). If you have tips, ideas, suggestions or anything
else that you think could help others in setting up their database for use
with Horde please let us know and we'll include them. (Or contribute to Horde
yourself and change this file on your own!) 
