IMP Installation Guide
Copyright 1998,1999 Charles J. Hagenbuch <chuck@horde.org>
Copyright 1999 Ivan E. Moore II <rkrusty@tdyc.com>

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

Last Updated: 04/14/99 



-------------------- 
Requirements for IMP 
====================


* PHP 3.0.7 or greater with IMAP support

 * A web server supported by PHP (Apache is most widely used)

 * An IMAP server to connect to.

 * HORDE module (you may have this already depending on how you obtained this
     package)

 * PERL if you want to use the config scripts.



----------------------
Optional Requirements:
======================


 * An SSL Web-server so the client connection to IMP is secure

 * 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.




--------------
Basic Features
==============


Languages Supported:

    Czech
    Danish
    German
    English
    Spanish
    French
    Dutch
    Belgium Dutch
    Norweigian
    Brazilian Portuguese
    Russian
    Slovak
    Swedish

Databases Supported:

     MySql
     PostgreSql
     Oracle (supported fairly well)
     Informix (not tested recently)




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


             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.



-=-=-=-=
Manually
-=-=-=-=


	  This is the hard way. It is, however, the most reliable. If you
	  want an easier method, examine the scripts section below.

	  The most common 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)  Change into the 'horde' directory, and untar/gzip imp.

               Mmake sure your directory structure is like this:

                  horde/
                  horde/imp

           4) 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.

	      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=postgres

              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.

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

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


           6)  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
           imp/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.  The file format is as follows:

                  http://a.site.com<sitename>graphic.gif

               ie...
          
                  http://www.horde.org/imp<IMP>imp.gif

            In this example, the link will be to http://www.horde.org/imp
            and will be labled as IMP and the graphic will be ./graphics/imp.gif
            You need to have whatever graphic you us in the graphics directory
            otherwise you will need to hackup the menu.php3 file and change
            the call to ./graphics.

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


           Scripts make everyone's life much easier.  Here are the 2 current
           methods for setting up IMP using scripts.  Both are still being
           tweaked so they are not guaranteed to work yet.



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


           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
           imp/setup.php3 since you won't be using it and IMP won't run
           while it is readable (for security reasons).



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


              In the weeks prior to 2.0 being frozen, Jason "ZeroDiViDe" Orcutt
           started work on a new setup engine that would give people the ability
           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 <imp dir> 
		 sh ./install.sh

           You should be able to point your browser to:

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

           When you are done be sure to disable it again!

		cd <imp dir>
		sh ./secure.sh

           At this point you can walk through the graphical setup program
           and configure all aspects of IMP.  Well, at least the major aspects. 
           The full process is probably about 95% complete at this time.
           As time progresses, this method will become the main method for
           configuring IMP and will handle everything for you.

	   It should be noted that it does *NOT* do extended LDAP or database
	   configuration at this time, please examing the DATABASE file for
	   information regarding database configuration, and the file
	   'horde/imp/config/ldap.php3' for LDAP configuration.



============
IMP Packages
------------


                Packages are by far the easiest way to install any program.  
           The reason I say this is because most of the work is done for you.
           By the use of scripts the maintainer of the package takes care of
           most configuration issues and the program is (most of the time)
           pretty much plug and play.

	        Setting up IMP can be a pain (as seen above) there are several
           steps you must take in order to get everything installed and
           operational.  Currently there are 2 types of packaging out there in
           use.  (there are probably more but these are the ones I know
           of). They are:  RPM (RedHat Package Management) which has a .rpm
           extension, Debian Package format which has a .deb extension.

               There is currently a Debian package being maintained by Ivan  
           Moore II.  It is available from http://snowcrash.tdyc.com/debian.php3
           and will shortly be available within the Debian distribution.  This
           package takes care of most configuration issues and still allows you
           to customize your IMP installation. This package also detects 
           Postgres and MySql installations and will automagically configure
           either for use with IMP. After installing this package you will
           have a functional IMP installation.

               There is no current RPM package for IMP. If you would like
           maintain one, please get in touch with use.
	   



--------------------------
Installation Notes for IMP 
==========================


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.  Also note that by
   turning on caching, other problems may occur.  There have been
   reports of random logouts, etc...

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.


----------------------
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.




-----------------------
PHP3 and Apache Changes
=======================


Well, not necessarily Apache, but your Web Server in general.  This piece
will cover what changes to your PHP3 and Web Server configuration you
need to do for things to work 100% (or pretty close).  

==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.  :)

First off, under the Data Handling section:

===Start===

;;;;;;;;;;;;;;;;;
; Data Handling ;
;;;;;;;;;;;;;;;;;
magic_quotes_gpc         = Off  ; magic quotes for incoming GET/POST/Cookie data
magic_quotes_runtime     = Off  ; magic quotes for runtime-generated data
magic_quotes_sybase      = Off  ; Use Sybase-style magic quotes

===End===

Make sure all your magic_quotes options are turned OFF!

If you need magic_quotes_gpc for another PHP application, you could also let 
magic_quotes_gpc = On on your php.ini and set it off per directory bases.
Just add the following lines on your access.conf apache configuration files :

    <Directory /path/to/your/imp/directory>
    php3_magic_quotes_gpc Off
    </Directory>"


and under the Dynamic Extensions section:

===Start===

;;;;;;;;;;;;;;;;;;;;;;
; Dynamic Extensions ;
;;;;;;;;;;;;;;;;;;;;;;
; if you wish to have an extension loaded automaticly, 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 index.htm default.html index.cgi

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.  


---------------------
Getting Help with IMP
=====================

There is an online, user-editable FAQ at http://horde.org/faq/. 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://horde.org/imp/. There are also two
mailing lists. One is the general IMP list, for development, discussion,
etc. It is imp@horde.org, and you can subscribe by sending an empty email to
imp-subscribe@horde.org.

The other list is the CVS commits list, 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
imp-cvs-subscribe@horde.org.

There are also web archives of both mailing lists. See, respectively:
  http://web.horde.org/mail/imp/
  http://web.horde.org/mail/cvs



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

    If you have found a bug you can add it to the Bug Tracking System
we have setup for the HORDE projects.  You can find it at:

http://web.horde.org/bugs

    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.

This version of the Installation manual was slapped together in part
by Ivan, Mike, Jason and of course, the man who started it all, the
man who keeps us on our toes, the man who'll probably never notice I
put this here but if he does I'm a dead man...Chuck.


Enjoy,

Chuck Hagenbuch and the IMP team
chuck@horde.org
----------------------------------------------------------------------
