==================
INSTALLING IMP 3.2
==================

This document contains instructions for installing the IMP web-based
mail client on your system.

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


OBTAINING IMP
-------------

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

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

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

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

[FIXME note on RPMs here]


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

To function properly, IMP requires the following:

  1. A working Horde installation.

     IMP runs within the Horde Application Framework, a set of
     common tools for Web applications written in PHP. You must
     install Horde before installing IMP.

     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/

     Many of IMP's prerequisites are also Horde prerequisites.
     Be sure to have completed all of the steps in the INSTALL
     file for the Horde Framework before installing IMP.

  2. The following PHP capabilities:

     a. 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, and can use
        IMAP-SSL and POP3-SSL if available.

        IMPORTANT NOTE: c-client support is broken in PHP 4.2.2 - 4.2.3.
        If you are using either of these versions you can not use any
        imap-2002 releases or else IMP will not function properly. If this
        is your situation, you have 2 options:

          1. If using PHP 4.2.3, you can apply this patch:
          http://lists.horde.org/archives/imp/Week-of-Mon-20021111/026936.html

          2. Downgrade to using the imap-2001a client.

        TROUBLESHOOTING TIP: If you notice strange behavior when running
        IMP (e.g. blank screens when accessing certain messages, blank
        message bodies) you should always try recompiling PHP with a different
        version of c-client.  The different versions of the c-client library
        and PHP do not always work well together, and often all it takes is
        to recompile with a different c-client version and the problems will
        go away.

  3. At least one IMAP or POP3 server.

     While IMP is an application that is installed on a Web server
     and is run from a Web browser, it is only an IMAP and POP3
     *client*, like Eudora or Outlook Express. You must have access
     to an IMAP or POP3 server (or multiple servers) on which your
     users' mail is stored in order to use IMP.

     IMAP is recommended over POP3 in order to let users maintain
     mail folders other than INBOX.

The following are not required, but are strongly recommended:

  1. Sendmail or equivalent.

     While Horde can inject mail via either a local sendmail or
     a remote SMTP server, the former is recommended for use with
     IMP for improved performance and error handling as well as
     a more accurate envelope.

  2. Turba, the Horde contacts manager.

     Turba is the Horde contact management application, designed to be
     integrated with other Horde applications to provide a unified
     interface to contact management throughout the Horde suite.
     Turba is available from

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

     Turba provides a local address book and an LDAP directory
     search function to IMP.

  3. Ispell, or a drop-in replacement.

     Ispell, or its enhanced cousin aspell, is used as IMP's
     spell-checking engine. You must install one of these, or
     a similar program with an ispell-compatible interface, to
     use IMP's spell-check feature.

     The differences between ispell and aspell are subtle but
     important. The author of ispell writes:

  [Aspell's] primary advantage is that it is better at making
  suggestions when a word is seriously misspelled. For example, when
  given "trubble", ispell will suggest only "rubble", where aspell
  suggests "trouble" (as its first choice" as well as "dribble",
  "rubble", and a lot of other words. Its disadvantage is that the
  approximate-matching algorithm is specific to English.

     As IMP supports multiple languages, the languages required
     by your userbase will probably provide an incentive to use
     one or the other. You can obtain International Ispell from

        http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html

     and aspell from

        http://aspell.sourceforge.com/


INSTALLING IMP
--------------

IMP 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. Conventionally, IMP is installed directly underneath
Horde in the webserver's document tree.

Since IMP 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/horde
   tar zxvf /path/to/imp-3.2.tar.gz
   mv imp-3.2 imp

and would then find IMP at the URL

   http://your-server/horde/imp/


CONFIGURING IMP
---------------

1. Configuring Horde for IMP

   a. Register the application

      With Horde 2.0/2.1
      In horde/config/registry.php, uncomment the stanza for IMP.
      Be sure to uncomment the ");" on the last line of the stanza.

      With Horde 2.2+
      In horde/config/registry.php, find the applications['imp'] stanza.
      The 'status' parameter should be marked '=> 'active''.

      If you have changed the location of IMP relative to Horde,
      either in the URL or in the filesystem or both, you must
      update the 'fileroot' and 'webroot' settings to their correct
      values.

   b. Optional: Enable IMP authentication

      If you would prefer that your users authenticate directly
      with IMP, without having to authenticate through Horde
      first, uncomment the lines

         $this->registry['auth']['login'] = 'imp';
         $this->registry['auth']['logout'] = 'imp';

      near the top of horde/config/registry.php.

      YOU WILL HAVE TO LOG IN TWICE IF YOU DON'T DO THIS.

2. Configuring IMP.

   To configure IMP, 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 configure IMP in conf.php and list your IMAP/POP3
   server names in servers.php (unless you demand that the user specify
   his own).

   The other files in config/ need only be modified if you wish
   to customize IMP's appearance or behavior, as the defaults will
   be correct for most sites.

   Note for international users:  IMP uses GNU gettext to provide local
   translations of text displayed by applications; the translations are
   found in the po/ directory.  If a translation is not yet available
   for your locale (and you wish to create one), or if you're having
   trouble using a provided translation, please see the po/README file
   for instructions.

3. Securing IMP

   There are two channels by which, unless steps are taken to avoid
   it, IMP encourages users to pass their IMAP and POP3 passwords
   around the Internet unencrypted.

   The first channel is between their browser and the Web server.
   We strongly recommend using an SSL-capable Web server to give
   users the option of encrypting communications between their
   browser and the Web server on which IMP is running; some sites
   may wish to disable non-SSL access entirely.

   The second channel is between the Web server and their IMAP
   or POP3 server. The simplest way to avoid this is to have the
   mail server running on the same system as the Web server, and
   configuring IMP to connect to the IMAP or POP3 server on
   "localhost" instead of on the Internet hostname. In cases where
   that is not possible, we recommend using IMAP-SSL or POP3-SSL to
   ensure that users' passwords remain safe after they have entrusted
   them to IMP.

4. Testing IMP

   Use IMP to login to a known working IMAP or POP3 server. Test at
   least the following:

     - Sending mail (via the "Compose" item in the menu bar)
     - Setting preferences (check to see if they survive after logging
       out and back in, if you are using an SQL or LDAP preferences
       system)
     - Reading mail
     - Changing folders


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

If you encounter problems with IMP, 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 Freenode Network
(irc.freenode.net).

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

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

Thanks for using IMP!

The Horde team
imp@lists.horde.org


$Horde: imp/docs/INSTALL,v 1.14.2.11 2003/10/08 18:08:52 slusarz Exp $
