Horde Installation Guide
Copyright 1998,1999,2000 Charles J. Hagenbuch <chuck@horde.org>
Copyright 1999 Ivan E. Moore II <rkrusty@tdyc.com>
Copyright 1999 Mike Hardy <mikeh@spark.com>
Copyright 1999, 2000 Jon Parise <jon@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.25 $
$Date: 2001/03/10 13:30:28 $


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


 * PHP 3.0.16 or greater -- SEE NEXT SECTION
 * a web server, preferably an SSL web server so that Horde modules can use a 
     secure connection.
 * phplib, included with the Horde distribution
 * Database supported by phplib (MySQL or PostgreSQL definitely work)
     (or a willingness to try shared memory in PHPLib)


------------
Notes on PHP
============

Versions of PHP earlier than 3.0.16 have bugs known to affect Horde.
Please save yourself (and the Horde mailing lists) hassles from these
known issues, and use PHP 3.0.16 or later.  (PHP 4 also works now.)

PHP needs to be compiled with IMAP support, and (depending on your
needs) probably with LDAP and MySQL/PostgreSQL support as well.

For Red Hat users, PHP RPMs are available at ftp://ftp.horde.org/pub/RPMS/
which are patched to resolve problems known to affect Horde.  Please see
the README file accompanying the RPMs for installation instructions and
a complete list of all required RPMs.

NOTE:  PHP 3.0.17 has a bug which causes Apache to crash on file uploads.
The symptom is usually a "Document contains no data" message when the
Apache process on the server segmentation faults.

This is a PHP bug, not a Horde bug.  You need to patch PHP to fix this;
the patches are available here:

    http://marc.theaimsgroup.com/?l=php-dev&m=97171796329239&q=p3
    http://marc.theaimsgroup.com/?l=php-dev&m=97174635324591&q=p3

NOTE:  PHP 3.0.16 has a bug which can cause the following error:

    Warning: Bad message number

This is a PHP bug, not a Horde bug.  You need to patch PHP's imap.c to
fix the php3_imap_fetchheader() function.  The patch is available here:

    http://cvsweb.php.net/viewcvs.cgi/php3/functions/imap.c.diff?r1=1.87&r2=1.88&diff_format=u

This patch is included in the PHP SRPM at ftp://ftp.horde.org/pub/SRPMS/

Also note that a number of users have reported problems when using the
"optimized" versions of the php.ini/php3.ini file that are distributed with
PHP.  We recommend using the standard -dist version as a template for your
local php.ini/php3.ini.

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

          There are several ways to install and configure Horde.  The first
       way is via a package; both Debian and Red Hat packages are available
       for Horde. Debian packages can be found at http://horde.tdyc.com.
       Red Hat packages can be found at ftp://ftp.horde.org/pub/RPMS/;
       please see the README file accompanying the RPMs for installation
       instructions and a complete list of all required RPMs.

           The second method is manually.  Below are the steps required to
       get Horde installed and functioning on your system.


           1)  obtain horde*.tar.gz 

           2)  untar/gzip it into the directory you want under your web
               tree; rename the directory from "horde-1.2.xx" to "horde"

               You should now have a directory structure like this:

                  horde
                  horde/config
                  horde/docs
                  horde/graphics
                  horde/lib
                  horde/locale
                  horde/phplib
                  horde/scripts
                  horde/scripts/database   [where sql scripts are]
                  horde/templates
		  
	   3) Configure phplib. There are instructions for doing this in
 	      horde/phplib/README.
	      
           4) In horde/config you will find a few files that you need to edit.
	      
	      The first file is "horde.php3.dist", and it needs the most work.
	      Start by copying it to "horde.php3", then open it in an editor.
	      
	      Edit $default->horde_root_url, and set it to the part of the URL
	      where Horde is installed, without the server name. For instance,
	      If you want Horde at http://www.mikehardy.net/horde, you will
	      say '/horde' here.
	      
	      If you would like to turn on our automated problem reporting
	      page (users will be able to give you feedback), you should
	      change $default->problem_reporting to "true;" and enter the
	      email address to send reports to.
	      
	      Just as the problem reporting may be turned on, if you want
	      to have automatic account signups you should change the value
	      to "true;" and enter the correct email address, or implement
	      a signup script in the skeleton we provide with
	      <horde>/signup.php3
	      
	      5) You should test the Horde installation now (see next
	      section.
	      
	      6) You now need to configure any Horde applications you have
  	      installed. Please see their respective INSTALL files for more
	      details.
	      
	      
------------------------------
Testing the Horde Installation
==============================

A comprehensive testing script, horde/test.php3, is included in the
Horde distribution.  This script makes sure that Horde, PHP, PHPLIB, the
database, etc. are all configured properly to support Horde applications.
PLEASE make use of this excellent testing tool before reporting problems
to the mailing lists!

You should test your Horde installation by pointing your browser to:

    http://example.com/horde/test.php3

The resulting page will show a red "No" after any element of PHP,
PHPLIB, etc. that is not properly configured.  You should also use the
"Click here to test PHPLIB" link, followed by clicking the "Reload"
link a few times, to make sure the counter is incremented.

If test.php3 identifies any problems, please re-read the installation
instructions to make sure you haven't missed anything, and consult the
FAQ at http://faq.horde.org/ for solutions to common problems.


-=-=-=-=-=-=-
Special Notes
-=-=-=-=-=-=-


===== Putting Horde as Apache's web-root ==========

A lot of people would like to have Horde be Apache's web-root, so that they
can simply specify a server and not have to type anything else in. If you
want to do this, you need to add these lines to your httpd.conf:

===Start===
DocumentRoot /home/httpd/html/horde/
Alias /horde/ /home/httpd/html/horde/
===End===

Where "/home/httpd/html/horde/" is where ever you have installed the
Horde package (with IMP under it).

Note that these lines are probably already in your httpd.conf somewhere,
and it might be best to just modify them, or add them individually in the
location the other references to "DocumentRoot" and "Alias" are.

====== Using Apache's config files to handle phplib prepends ========

# Added for Horde   
<Directory /home/httpd/html/horde>  
    Options Indexes FollowSymLinks
    AllowOverride None
    order allow,deny
    allow from all
    <IfModule mod_php3.c>
        php3_include_path '/home/httpd/phplib:.'
        php3_auto_prepend_file /home/httpd/phplib/prepend.php3
        php3_magic_quotes_gpc Off
        php3_track_vars On
    </IfModule>
    <IfModule mod_php4.c>
        php_value include_path '/home/httpd/phplib:.'
        php_value auto_prepend_file /home/httpd/phplib/prepend.php3
        php_flag register_globals On
        php_flag magic_quotes_gpc Off
        php_flag track_vars On
    </IfModule>
</Directory>

(Of course, you need to change "/home/httpd/html/horde" to the path
where you have Horde installed on your system, and "/home/httpd/phplib"
to the path where you have PHPLIB installed.)

Adding something like the above to Apache's httpd.conf (Apache now
recommends that access.conf and srm.conf be left empty) will allow
per directory loading of the required phplib files.  Otherwise if you throw
the prepend line into your php3.ini file, these files will be loaded for
every page that is loaded on your server which could be bad if one of the
phplib files were to get hosed.  Doing the above limits your possible problems
due to a mistake or bad php or whatever to just your horde web tree.

To explain the above I'll break it down.

The first 4 lines:

    Options Indexes FollowSymLinks
    AllowOverride None
    order allow,deny
    allow from all

are normal Apache settings.  You can change them to whatever you want, I just
used the defaults.

The next lines are what we need for things to work:

    <IfModule mod_php3.c>
        php3_include_path '/home/httpd/phplib:.'
        php3_auto_prepend_file /home/httpd/phplib/prepend.php3
        php3_magic_quotes_gpc Off
        php3_track_vars On
    </IfModule>
    <IfModule mod_php4.c>
        php_value include_path '/home/httpd/phplib:.'
        php_value auto_prepend_file /home/httpd/phplib/prepend.php3
        php_flag register_globals On
        php_flag magic_quotes_gpc Off
        php_flag track_vars On
    </IfModule>

the include path will have both your phplib include path, ie..where your
core phplib files are, and the path to where you placed your horde phplib
files.  

Now keep in mind you really need to read the README in the phplib directory
of horde as there are some things you need to take care of in that prepend 
file.  Also please read imp/docs/SECURITY for security recommendations,
and additional httpd.conf lines you can add to protect sensitive data (e.g.
passwords) in your Horde/IMP configuration files.


-----------------------
Getting Help with Horde
=======================

There is an online, user-editable FAQ at http://faq.horde.org/. Use it,
and add anything that you run into to it, so that others can benefit from
everything you figure out, and vice versa...

There is a web page for Horde at http://web.horde.org/. There are also
three mailing lists. One is the general IMP list, for feature requests,
bug questions, discussion, etc. It is imp@lists.horde.org, and you can
subscribe by sending an emp ty email to imp-subscribe@lists.horde.org.

The second list is the developers list at dev@lists.horde.org, and it is
targeted at people who have serious feature requests or are trying to
extend or debug IMP and other Horde modules. You may subscribe to it by
sending an empty mail to dev-subscribe@lists.horde.org.

The third list is the CVS list at cvs@lists.horde.org, and most of the mail
on it is automatically generated announcements of changes to the CVS code.
Developers should definitely be on it, and anyone else who is curious
about the status of Horde development is welcome to join it by sending
email to cvs-subscribe@lists.horde.org.

There are also web archives of all the mailing lists. See:
  http://horde.tdyc.com                                    

=-=-=-=-=-=-
Found A Bug?
=-=-=-=-=-=-

    If you have found a bug you can add it to the Bugzilla bug system
we have setup for the Horde projects.  You can find it at:

http://bugs.horde.org

    Please verify that the bug is not already in the database and also
please be as descriptive as possible.  Fill out all the options.  You may
think it's something that affects everyone, but a lot of times it's 
specific to a browser or operating system.  So please be thorough.  In
the case of Bug Tracking, there is never too much information or
documentation.



----------------------------------------------------------------------
We hope you find Horde useful and easy to use.  We thank you for taking
the time to try it and if you ever have any questions, just ask.

Enjoy,

The Horde Team
dev@lists.horde.org
---------------------------------------------------------------------
