IMP Installation Guide
Copyright 1998,1999 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>

This code is licensed under the GNU Public License.
See the file COPYING in this directory.
Last Updated: 02/02/2000 [IEM]

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

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

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

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

   * PHP 3.0.12 or greater with IMAP support (PHP4 works now)
  
   * 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.

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

   * PHPLIB 7 or greater


  ---------------
  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 'horde/imp/config/ldap.php3' for configuration
     instructions here.


+++++++++++++++
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 srm.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) Scripts
    =-=-=-=-=-

       First untar the files:
           cd <Document Root> #(i.e. /usr/local/apache/htdocs/ /www/htdocs/)
           tar -xzf horde-(ver).tar.gz 
           cd horde-(ver)
           tar -xzf imp-(ver).tar.gz 


           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

        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.



        ===========
        impsetup.pl
        ===========

           *** NOTE *** This is really outdated *** NOTE*** impsetup.pl was
	   originally started by Jason (same as the setup.php3) and as he
	   started to work on the setup.php3 process he dumped it off onto
	   Ivan.  Ivan has since slapped it together and finished it up. To
	   use the script all you have to do is:

                 cd <impdir>/config/scripts
                 ./impsetup.pl    (you may have to do perl ./impsetup.pl)

           Fill out all options under each of the sections and after you
	   finish them you should have a functioning IMP installation.
	   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
	   while it is readable (for security reasons).

    -=-=-=-=
    B) 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

           5) IMP and HORDE use large libraries of PHP code. They are
              customized to your specific installation using a build
              program to make them smaller. You need to build those
              libraries now.

           Go into 'horde/lib/src' and run the following command:

                  ./build.pl --help

           It will print out instructions on its use.

           6) Move into 'horde/imp/lib/src' and run the 'build.pl' there.


                  ./build.pl --help

              It will print out instructions on its use.

           The one nice thing about build.pl is that you can create a
           file called build.opts in that same directory and put all
           your options you want to use in that file in this format:

                          option=value

              An example of this would be:

                          database=pgsql

           When build.pl runs it will check that file and use any values
           in it as defaults.  This is nice for keeping your
           configuration the same and automating upgrades/installs.

           This program will build the horde library containing only the
           routines necessary for the options you configured it for.

           At this point, you're horde library and IMP libraries are
           built.


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


              At this point I'd like to point out the use of a perl based
           script called impsetup.pl which is in 'horde/imp/config/scripts'.  
           Since you are reading through the harder method of setting 
           things up this script would make your life easier. Or you
           can continue on.

               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.

           'horde/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/imp/config/scripts'.

           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:
  ===============
  index.php3 is the root of the frame system. If you want IMP to use a secure
  connection (SSL), then you need to somehow make sure that users access IMP
  as https://your.server.here/your/path/to/imp/, not as http://blah... 

  Also, note that the file setup.php3 can be used to configure IMP
  over the web. This is insecure. For this reason, it should not be
  readable while IMP is in use, and IMP, in fact, checks to make sure
  that it is not.

  All caching flags have been flipped in order to make sure that no 
  caching takes place.  You can turn on web local caching within your
  defaults.php3 file (default->cache_pages) but it isn't recommended
  as it is a security risk.  Netscape doesn't handle non-cached pages
  very well and if you are in a compose window and you resize your
  screen you will lose the data inside of it. Mozilla/Netscape5 will change 
  this.

  ---------------
  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 /usr/share/horde>
  Options Indexes FollowSymLinks
  AllowOverride None
  order allow,deny
  allow from all
  php3_include_path /etc/horde:/usr/lib/phplib
  php3_auto_prepend_file /etc/horde/prepend.php3
  php3_magic_quotes_gpc Off
  </Directory>


  Adding something like the above to either Apaches httpd.conf or access.conf
  (it doesn't seem to matter which conf file it goes in anymore) 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 3 lines are what we need for things to work:

    php3_include_path /etc/horde:/usr/lib/phplib
    php3_auto_prepend_file /etc/horde/prepend.php3
    php3_magic_quotes_gpc Off

  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.  The default location is in horde/phplib but for a Debian install,
  which is where the above lines are from, I moved all the horde config
  files into /etc/horde.  These included the files out of horde/phplib.

  So your configuration may look something like this:

  (for this example let's say your web tree is /home/httpd/html and your
  phplib files are stored in /home/httpd/phplib and your horde files are
  in /home/httpd/html/horde.  And let's say you left your horde phplib files
  where they were, in /home/httpd/html/horde/phplib)

    Your Directory config would look like this:

    <Directory /home/httpd/html/horde>
    Options Indexes FollowSymLinks
    AllowOverride None
    order allow,deny
    allow from all
    php3_include_path /home/httpd/html/horde:/home/httpd/phplib
    php3_auto_prepend_file /home/httpd/phplib/prepend.php3
    php3_magic_quotes_gpc Off
    </Directory>


  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.



+++++++++++++++++++++
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@horde.org, and you can subscribe by sending an empty 
email to imp-subscribe@horde.org.

The second list is the developers list at dev@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@horde.org

The third list is the CVS list at cvs@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@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@horde.org
----------------------------------------------------------------------
