
INSTALLING THE HORDE 2.0 FRAMEWORK
==================================

This document contains instructions for installing the Horde
Framework on your system.

For information on the capabilities and features of Horde, see
the file README in the top-level directory of the Horde
distribution.


OBTAINING HORDE
---------------

The Horde Framework can be obtained from the Horde website and FTP
server, at

   http://www.horde.org/horde/
   ftp://ftp.horde.org/pub/horde/

Bleeding-edge development versions of Horde and its applications are
available via CVS; see the file docs/HACKING for information on
accessing the Horde CVS repository.

You will probably also want one or more Horde applications, since
Horde doesn't do much by itself; a list of available applications,
with links to descriptions and downloads, can be found at 

   http://www.horde.org/projects.php

While previous versions of Horde were numbered to correspond with a
particular version of the IMP webmail application, that is no longer
true as of Horde version 2.0. The current version of Horde will work
with the current version of Horde applications.

[FIXME note on RPMs here]


PREREQUISITES
-------------

The following prerequisites are REQUIRED for Horde to function
properly.

  1. A webserver that supports PHP.

     Horde and its applications are developed under the Apache
     webserver, which we recommend. Apache is available from 
   
        http://www.apache.org/

     Horde has also been reportedly used successfully under Microsoft
     IIS in the past.

  2. PHP 4.1.0 or above, or PHP 4.0.6 with a manually upgraded PEAR.

     PHP is the interpreted language in which Horde is written.
     You can obtain PHP at
 
        http://www.php.net/

     Follow the instructions in the PHP package to build PHP 
     for your system. If you use Apache, be sure to build PHP
     as a library with the

         --with-apache
     or
         --with-apxs

     options to ./configure, and not as a standalone executable.

     The following PHP options are required by Horde (listed with 
     their own prerequisites and configure options). In many cases,
     the required libraries and tools can be obtained as packages from
     your operating system vendor.

       a. Gettext support. (--with-gettext)
       
          Gettext is the GNU Translation Project's localization library.
          Horde uses gettext to provide local translations of text 
          displayed by applications. Information on obtaining the
          gettext package is available at

             http://www.gnu.org/software/gettext/gettext.html
 
       b. XML support. (--with-xml)

          Horde's help engine requires XML support. While some 
          webservers (including recent Apache versions) have XML
          libraries built-in, others will require the expat XML
          parser libraries, available from
          
             http://www.jclark.com/xml/expat.html

     The following PHP options are either recommended or are required
     by a specific Horde application (as noted in [brackets]):

       c. A preferences container.

          Horde applications can store user preferences in an SQL
          database, an LDAP directory, or in PHP sessions. 

          For SQL database preferences storage, Horde is
          thoroughly tested on MySQL (--with-mysql) and PostgreSQL
          (--with-pgsql) and has been reported to work with Oracle
          (--with-oracle). It may also work with any other database
          supported by PEAR, but they are untested.

          Preferences can also be stored via LDAP (--with-ldap). 

          Alternatively, preferences can be stored in PHP sessions,
          which requires no external programs or configure options,
          but which will not maintain preferences between sessions.


          While the LDAP or database server need not be running on
          the machine onto which you are installing Horde, the
          appropriate client libraries to access the LDAP or
          database server must be available locally.

       d. Mcrypt support (--with-mcrypt)

          Mcrypt is a general-purpose cryptography library which is
          broader and more efficient than PHP's own cryptographic
          code. You can obtain mcrypt from
 
             http://mcrypt.hellug.gr/

          Building PHP without mcrypt support will not stop Horde
          from working, but will force it to use weaker encryption.

       e. [IMP] IMAP and POP3 support (--with-imap)

          PHP uses the UW-IMAP c-client library to provide IMAP and
          POP3 support. C-client is available from

             ftp://ftp.cac.washington.edu/imap/

          IMP requires IMAP and POP3 support in PHP.

The following non-PHP prerequisites are RECOMMENDED, or are REQUIRED
if you use a specific Horde application (as noted in [brackets]):

  1. Sendmail or equivalent.

     Horde uses sendmail, or a program that implements the
     sendmail(8) API (as included with postfix, qmail, and exim,
     among others). If your system does not already have a full
     mail transport with a sendmail interface, you can configure
     Horde to speak directly with a remote SMTP server, but this
     may incur a performance penalty.

     A local sendmail interface is strongy recommended when 
     using IMP.


INSTALLING HORDE
----------------

Horde is written in PHP, and must be installed in a web-accessible
directory. The precise location of this directory will differ from
system to system. If you have no idea where you should be installing
Horde, install it directly under the root of your webserver's document
tree.

Since Horde is written in PHP, there is no compilation necessary;
simply expand the distribution where you want it to reside and rename
the root directory of the distribution to whatever you wish to appear
in the URL. For example, with the Apache webserver's default document
root of '/usr/local/apache/htdocs', you would type:

   cd /usr/local/apache/htdocs
   tar zxvf /path/to/horde-2.0.tar.gz
   mv horde-2.0 horde

and would then find Horde at the URL
 
   http://your-server/horde/

IMPORTANT NOTE FOR USERS OF PHP 4.0.6: 

You must manually install a newer version of the PEAR library for
Horde to function. PEAR is the PHP Extension and Application
Repository, a set of standard and quality-assured libraries for use
with PHP. If you are using a version of PHP below 4.0.7, you will need
to obtain a newer PEAR from
 
   http://www.horde.org/pear/

Follow the directions at that URL to install PEAR.

If you are using PHP 4.1.0 or above, you already have a suitable PEAR.


CONFIGURING HORDE
-----------------

1. Configuring the web server

   Horde requires the following webserver settings. Examples shown are
   for Apache; other webservers' configurations will differ.

   a. PHP interpretation for files matching "*.php"   

         AddType application/x-httpd-php .php
         
   b. "index.php" as an index file (brought up when a user requests
      a URL for a directory)

         DirectoryIndex index.php

2. Creating databases

   The specific steps to create a preferences storage container depend
   on which database you've chosen to use. 

   First, look in scripts/db/ to see if a "_create" script already
   exists for your database. If so, you should be able to simply 
   execute that script as superuser in your database.

   Be sure to change the default password, "horde", to something
   else before creating the tables! (Remember to use this password
   when you configure Horde in the next step.)   

   If such a script does not exist, you'll need to build your own, using
   the files auth.sql, prefs.sql, and category.sql as a starting point.
   If you need assistance in creating databases for a database for
   which no "_create" script exists, you may wish to let us know on
   the Horde mailing list.

   Note that the "_drop" scripts in the scripts/db/ directory remove
   the changes made by the "_create" scripts.

3. Configuring Horde

   To configure Horde, change to the config/ directory of the
   installed distribution, and make copies of all of the configuration
   "dist" files without the "dist" suffix:

      cd config/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Documentation on the format of those files can be found in each
   file. You must at least complete the "Preferences System Settings"
   section of horde.php and provide paths to helper applications in
   mime_drivers.php. Configuration of applications in registry.php is
   documented in the INSTALL file of each application.

   The other files in that directory need only be modified if you wish
   to customize Horde's appearance or behaviour -- the defaults will
   work at most sites.

4. Securing Horde

   a. Passwords

      Some of Horde's configuration files contain passwords which local
      users could use to access your database. It is recommended to ensure
      that at least the Horde configuration files (in config/) are not
      readable to system users. There are .htaccess files restricting
      access to directories that do not need to be accessed directly;
      before relying on those, ensure that your webserver supports
      .htaccess and is configured to use them, and that the files in
      those directories are in fact inaccessible via the browser.

      An additional approach is to make Horde's configuration files
      owned by the user 'root' and by a group which only the webserver
      user belongs to, and then making them readable only to owner and
      group. For example, if your webserver runs as www.www, do as
      follows:

         chown root.www config/*
         chmod 0440 config/*

   b. Sessions

      Session data -- including hashed versions of your users'
      passwords, in some applications -- may not be stored as securely
      as necessary.

      If you are using file-based PHP sessions (which are the default),
      be sure that session files are not being written into /tmp with
      permissions that allow other users to read them. Ideally, change
      the 'session.save_path' setting in php.ini to a directory only
      readable and writeable by your webserver.


5. Testing Horde
   
   Once you have configured your webserver, PHP, and Horde, bring up the
   included test page in your Web browser to ensure that all necessary
   prerequisites have been met. If you installed Horde as described
   above, the URL to the test page would be
   
      http://your-server/horde/test.php
   
   Check that your PHP and PEAR versions are acceptably recent, that
   all required module capabilities are present, and that
   magic_quotes_runtime is set to Off. Then note the "Session counter: 1"
   line under "PHP Sessions", and reload the page. The session counter
   should increment. 


CONFIGURING APPLICATIONS
------------------------

A list of available Horde applications can be found at 

   http://www.horde.org/projects.php

Instructions on configuring Horde applications can be found in
the INSTALL file in the application's docs/ directory.


OBTAINING SUPPORT
-----------------

If you encounter problems with Horde, help is available! 

The Horde Frequently Asked Questions List (FAQ), available on the Web
at
 
  http://www.horde.org/faq/

The Horde Project runs a number of mailing lists, for individual
applications and for issues relating to the project as a whole.
Information, archives, and subscription informatoin can be found at

  http://www.horde.org/mail/

Lastly, Horde developers, contributors and users also make occasional
appearances on IRC, on the channel #horde on the Open Projects Network
(irc.openprojects.net).

Please keep in mind that Horde is free software written by volunteers.
For information on reasonable support expectations, please read

  http://www.horde.org/support.php

Thanks for using Horde!

The Horde team
horde@lists.horde.org


$Horde: horde/docs/INSTALL,v 1.28.2.11 2002/01/03 01:51:03 rich Exp $
