IMP 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 Doug Lumpkin <dougel@thecalling.net>
Copyright 2000 Brent J. Nordquist <bjn@horde.org>

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

$Author: bjn $
$Revision: 1.1.2.30 $
$Date: 2001/03/10 13:31:31 $

+++++++++
Overview:
+++++++++

This file contains the following sections:
	  + Overview
          + Requirements for IMP
          + Installing IMP
          + Additional Notes for IMP
          

+++++++++++++
Requirements:
+++++++++++++

  ----------------
  Mandatory Items:
  ================

   * PHP 3.0.16 or greater with IMAP support (--with-imap) -- SEE NEXT SECTION
  
   * A web server supported by PHP (Apache is most widely used)
  
   * An IMAP server to connect to.

   * Horde MUST be installed. If it is not already, please download it, and
     follow the instructions in its INSTALL file BEFORE installing IMP.  In
     particular, you should test Horde to make sure that PHP, PHPLIB, etc.
     are all working, before proceeding with installing IMP; please see the
     section "Testing the Horde Installation" in horde/docs/INSTALL.

   * Perl if you want to use the manual config scripts.

   * PHPLIB must be installed and working with Horde.


  ---------------
  Optional Items:
  ===============

   * An SSL Web-server so the client connection to IMP is secure
       (Apache+mod_ssl+OpenSSL is popular)

   * A database, and database support compiled into PHP, if you want support
       for user preferences and addressbooks. See the DATABASE file in this
       distribution for installation and configuration instructions here.

   * LDAP support compiled into PHP if you want support for LDAP
     searches. See the file 'imp/config/ldap.php3' for configuration
     instructions here.


+++++++++++++
Notes on PHP:
+++++++++++++

Versions of PHP earlier than 3.0.16 have bugs known to affect IMP.
Please save yourself (and the IMP 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 IMP.  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 an IMP 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 an IMP 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/


+++++++++++++++
Installing IMP:
+++++++++++++++

  ---------------------------
  Changes for your Webserver:
  ===========================

  This piece will cover what changes to your PHP3 and Web Server
  configurations you need to make.

  ==php3.ini==

  In your php3.ini file there are a few things you need to do so that 
  content appears the way it should and also so that you can use key
  features such as IMAP.  :)

  Under the Dynamic Extensions section:

  ===Start===

  ;;;;;;;;;;;;;;;;;;;;;;
  ; Dynamic Extensions ;
  ;;;;;;;;;;;;;;;;;;;;;;
  ; if you wish to have an extension loaded automatically, use the
  ; following syntax:  extension=modulename.extension
  ; for example, on windows,
  ; extension=msql.dll
  ; or under UNIX,
  ; extension=msql.so
  ; Note that it should be the name of the module only, no directory information
  ; needs to go here.  Specify the location of the extension with the 
  ; extension_dir directive above.
  extension=imap.so      ; Added for IMAP support
  extension=mysql.so     ; Added for MySQL support
  extension=pgsql.so     ; Added for PostgreSQL support
  extension=ldap.so      ; Added for LDAP support

  ===End===

  You'll need to add the appropriate extensions for what you'll be using.  
  Remember that if your running this server on a Windows box you'll be using
  .dll extensions instead of .so extensions.   

  ===Apache's httpd.conf===

  (NOTE:  Older versions of Apache have DirectoryIndex in the srm.conf file,
  but Apache now recommends that all configuration directives be placed in
  httpd.conf)

  Now this file can look different depending on version and configuration so
  I will just show the actual line within the file that we are concerned
  with.

  DirectoryIndex index.html index.php3

  You need to make sure that index.php3 is listed in your DirectoryIndex
  line in order for IMP to show up properly. I'm sure this line is 
  called different things with different servers but the basic idea is
  that you want the index.php3 file to be a default in the same sense that
  index.html is.  


  -------------------
  Installation of IMP
  ===================

     There is more than one way to setup IMP. We will cover each of them
     in more detail here. There is more information below on database
     configuration as well.


    =-=-=-=-=-=
    A) Packages
    =-=-=-=-=-=

       For Red Hat users, RPMs are available 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.  NOTE that you
       will still need to set up your database; see "Database Configuration"
       below for details.


    =-=-=-=-=-
    B) Scripts
    =-=-=-=-=-

       <Document Root> refers to the top of your web server documents
       tree (for example, /usr/local/apache/htdocs or /home/httpd/html).

       First untar the IMP files UNDER the Horde directory, and rename
       the directory "imp":

           cd <Document Root>/horde
           tar -xzf imp-(ver).tar.gz 
           mv imp-(ver) imp

       Scripts make everyone's life much easier.  Here are the two current
       methods for setting up IMP using scripts.  

       Of the two methods, setup.php3 is the preferred method.


        ==========
        Setup.php3
        ==========

        "setup.php3" is the name of a PHP system that will allow you
	to configure IMP (out of the box) via the web.  For security reasons,
	it is disabled by default, but you can enable it by saying:

             cd <horde dir> 
             sh ./install.sh

           You should be able to point your browser to:

             http://<your imp server>/<your horde home>/setup.php3

           At this point you can walk through the graphical setup program
           and configure nearly all aspects of IMP.  Well, at least the major 
	   aspects. 

           When you are done be sure to disable it again!

              cd <horde dir>
              sh ./secure.sh
	      
	To prevent 3rd party access to potentially security relevant internal
	server information, secure.sh disables test.php3
	
        It should be noted that it does *NOT* do extended LDAP or database
	configuration at this time, please examine the DATABASE file for
	information regarding database configuration, and the file
	'horde/imp/config/ldap.php3' for LDAP configuration.
	
        Additionally, there are several lower-level configuration parameters
	that you may change directly by editing various config files in the
	<horde>/imp/config directory. Most of them have fairly
	self-explanatory names, or are commented to describe their
	functionality.
	
    -=-=-=-=
    C) Manually
    -=-=-=-=


       This is the hard way. It is, however, the most flexible. If you want
       an easier method, examine the scripts section above.
       
       The manual method of installing IMP is to grab the tarball, untar
       it somewhere and run through the code making all the changes you
       need by hand.  In order to do this you must remember that IMP and
       Horde have been broken up into 2 separate distributions. You need
       Horde to use IMP.  Horde contains the base functions for all Horde
       based applications.  Here is the process for doing all of this by
       hand.
       
       1) Obtain horde*.tar.gz and imp*tar.gz 
       (can be combined depending on who packaged it)
       
       2) untar/gzip horde into the directory you want.
       
       3) Follow the instructions in the horde/INSTALL file to properly
          setup the Horde module.  
       
       4) Change into the 'horde' directory, and untar/gzip imp.
          Change the directory name from "imp-2.2.xx" to "imp"
	  Make sure your directory structure is like this:

                  horde/
                  horde/imp
       
       7) Change into 'horde/imp/config' and make changes to the
          config files. 


               Within the 'imp/config' directory are several .php3 files as
           well as a couple .txt files. These files store your customizable 
           configuration options. defaults.php3 is the one you need to make 
           changes to before IMP will function properly. The others can be
           left alone to begin with.

           'imp/config/defaults.php3' contains a large number of
           defaults that you'll need to configure for your system, such as
           the default IMAP server, whether or not users can pick a
           different server, etc... The file is fairly well documented, so
           you should be able to pick out what you need to change fairly
           easily.

           There are several example config files sitting in 
           horde/imp/config/examples. There are 2 that are designed to 
           be almost plug and play for postgres and mysql installs.  The
           only thing you would have to change is the hostnames and any
           options you want to disable/enable. These default files are
           under the impression that you configured your database using one
           of the database setup scripts located in 'horde/scripts/database'.

           Please note that if you use this procedure, you need to chmod 000
           horde/setup.php3 since you won't be using it - and IMP won't run
           for security reasons while it is readable.
	   
           menu.txt is a new file that will allow you to add links to
           the menu.  For more information on this please take a look
           at the menu.txt file itself.
	   
           There is also a MOTD.html file in imp/config that will allow
           you to attach a message of the day to the bottom of the login 
           screen to alert your users to important information in a timely way.


++++++++++++++++++++++++
Additional Notes for IMP 
++++++++++++++++++++++++

  ----------------------
  Database Configuration
  ======================


  One of the biggest problems people have while installing IMP is getting
  the database setup.  Questions range from how to install the database
  to how to configure it for IMP.  While it's not our job to help you
  install your database, we are working on ways to help you configure it.

  There is now a separate text file for help with database configuration.
  Please checkout DATABASE in the same directory for further assistance.

  ---------------
  Security Notes:
  ===============

  Please refer to the docs/SECURITY file for notes on security issues.

  ---------------
  Language Notes:
  ===============
  Netscape for some reason reports language choices in reverse order.  So
  if you have french as your primary language and english as a secondary and
  you go to the IMP page, it may show up in English.


  -------------------
  Apache & PHP Notes:
  ===================

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

  A lot of people would like to have IMP 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/htdocs/horde/imp
  Alias /horde/ /home/httpd/htdocs/horde/
  ===End===

  Where "/home/httpd/htdocs/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 IMP
+++++++++++++++++++++

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 IMP at http://www.horde.org/imp/. 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 empty 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 IMP 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 tracker
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 or description.


----------------------------------------------------------------------
We hope you find IMP 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 IMP team
imp@lists.horde.org
----------------------------------------------------------------------