================================================
 Installing Horde Groupware Webmail Edition 1.1
================================================

:Last update:   $Date: 2010-09-27 12:34:57 $
:Revision:      $Revision: 1.13.4.1 $
:Contact:       horde@lists.horde.org

.. contents:: Contents
.. section-numbering::

This document contains instructions for installing Horde Groupware Webmail
Edition on your system.

For information on the capabilities and features of Horde Groupware Webmail
Edition, see the file README_ in the top-level directory of the Horde
Groupware Webmail Edition distribution.


Obtaining Horde Groupware Webmail Edition
=========================================

Horde Groupware Webmail Edition can be obtained from the Horde website and FTP
server, at

   http://www.horde.org/webmail/

   ftp://ftp.horde.org/pub/horde-webmail/

Or, better yet, use a mirror that is closer to you.  The mirror list can be
found at:

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

The FTP directory contains the Horde Groupware Webmail Edition PHP files which
can be unpacked using ``tar`` and ``gunzip`` (see `Installing Horde Groupware
Webmail Edition`_, below).


Quick Install
=============

These are very terse instructions how to install Horde Groupware Webmail
Edition and its prerequisites on a LAMP sytem. They are addressed to
experienced administrators who know exactly what they are doing.  For more
detailed instructions, start reading below at Prerequisites_.

1. Compiling PHP for Apache::

     cd php-x.x.x/
     ./configure --with-apxs=/usr/sbin/apxs \
                 --with-gettext --with-dom --with-mcrypt --with-imap \
                 --with-iconv --enable-mbstring=all --enable-mbregex \
                 --with-gd --with-png-dir=/usr --with-jpeg-dir=/usr \
                 --with-mime-magic=/user/share/misc/magic.mime \
                 [--with-mysql|--with-pgsql|--with-oci8]
     make
     make install

2. Restart Apache.

3. Extract tarball::

     cd /usr/local/apache/htdocs
     tar zxvf /path/to/horde-webmail-x.y.z.tar.gz
     mv horde-webmail-x.y.z horde

4. Configure Horde Groupware Webmail Edition::

     ./scripts/setup.php

5. Test Horde Groupware Webmail Edition::

     http://your-server/horde/test.php

6. Finish configuration::

     http://your-server/horde/

   Go to Administration => Setup => Horde


Prerequisites
=============

The following prerequisites are **REQUIRED** for Horde Groupware Webmail
Edition to function properly.

1. A webserver that supports PHP.

   Horde Groupware Webmail Edition is developed under the Apache webserver,
   which we recommend. Apache is available from

      http://httpd.apache.org/

   Horde Groupware Webmail Edition has also been reportedly used successfully
   under Microsoft IIS, among others.

2. A web server with PATH_INFO support.

   The dynamic webmail interface of Horde Groupware Webmail Edition requires a
   web server that correctly sets the PATH_INFO environment variable for all
   PHP scripts. Every modern web server supports this, but you might have to
   enable this feature in the web server configuration.  e.g. Apache servers
   require::

      AcceptPathInfo On

   Lighttpd servers require::

     "broken-scriptfilename" => "enable"

3. PHP 4.3.0 or above.

   PHP is the interpreted language in which Horde Groupware Webmail Edition 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 one of the following
   options::

       --with-apache
       --with-apxs
       --with-apxs2

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

   The following PHP options are **REQUIRED** by Horde Groupware Webmail
   Edition (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
      Groupware Webmail Edition 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

      See also note below on configuring Translations_.

   b. XML and DOMXML support. ``--with-dom``

      Horde Groupware Webmail Edition's help engine and component setup
      require 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://expat.sourceforge.net/

      .. Important:: You must have **both** XML libraries installed for Horde
                     Groupware Webmail Edition to work properly!

      Older versions of PHP also require ``--with-xml`` to enable the
      SAX XML functions. With recent versions of PHP, this is enabled
      by default.

   c. IMAP and POP3 support ``--with-imap``

      Horde Groupware Webmail Edition **requires** the PHP imap extension to
      provide IMAP and/or POP3 support.  To compile the imap extension, the
      UW-IMAP c-client libray must be present on your system.  For help with
      compiling the imap extension ninto PHP, you can view the PHP imap manual
      entry:

         http://www.php.net/imap

      Because installation of the imap extension can be a non-trivial matter,
      further configuration help/advice follows.

      The UW-IMAP c-client library is available from

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

      The most recent code is normally located in a file named 'imap.tar.Z'.

      After building the c-client library (instructions are at the top of
      the Makefile in the base directory of the UW imap package), you may
      need to rename the compiled library file so the local build system can
      find it.  For example, compilation of c-client results in a file named
      'c-client.a' in the 'c-client' directory.  On Linux (at least) this file
      needs to be renamed or linked to libc-client.a, e.g.:
      
         ln -s c-client.a libc-client.a

      Horde Groupware Webmail Edition can use IMAP-SSL and POP3-SSL if
      available.  SSL support needs to be built-in to both the c-client
      library and the PHP extension (see the ``--with-imap-ssl`` configure
      option to PHP).

      If using TLS or SSL to connect to the IMAP/POP3 server, OpenSSL support
      is **required** in PHP. See `OpenSSL Support`_ below.

      .. Tip:: If you notice strange behavior when running Horde Groupware
               Webmail Edition (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.

      .. Tip:: If running the webserver changerooted (i.e. the default setting
               on OpenBSD), you may need additional configuration on your
               system to ensure the c-client library works properly.
               See: `Configuring c-client for changerooted webservers`_

      .. _`Configuring c-client for changerooted webservers`: http://lists.horde.org/archives/imp/Week-of-Mon-20050321/041502.html

   d. File Upload Support

      File upload support is **required** to allow attachments in mail
      composition and to allow various importing features to work (e.g.
      importing PGP or S/MIME keys, importing mbox files). To enable file
      upload support:

          1. In your php.ini file, the following line **must** be present::

                file_uploads = On

          2. Your temporary upload directory **must** be writable to the user
             the web server is running as. If you leave the configuration
             option ``upload_tmp_dir`` blank in ``php.ini``, PHP will use the
             default directory compiled into it (normally ``/tmp`` on
             Unix-like systems).

          3. Set the maximum size of the uploaded files via the
             ``upload_max_filesize`` configuration option in ``php.ini``. For
             example, to allow 5 MB attachments, place the following line in
             your ``php.ini`` file::

                upload_max_filesize = 5M

       If either ``file_uploads`` is turned off, or your temporary upload
       directory is *not* writable by the server, all file upload
       functionality will be disabled by Horde Groupware Webmail Edition and
       will not be available to the user.

       See the `File Uploads`_ FAQ entry for further information.

   The following PHP options are **RECOMMENDED** to enable advanced features
   in Horde Groupware Webmail Edition:

   a. A preferences container.

      Horde Groupware Webmail Edition can store user preferences in an SQL
      database, an LDAP directory, an IMSP server, a Kolab server, or in PHP
      sessions. An SQL database is used and configured by default.

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

      Preferences can also be stored via LDAP (``--with-ldap``), Kolab
      (``--with-ldap``), and IMSP.

      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, database, Kolab, or IMSP server need not be running on
      the machine onto which you are installing Horde Groupware Webmail
      Edition, the appropriate client libraries to access the server must be
      available locally.

      If a preference container is not configured, no preference options will
      be configurable via Horde Groupware Webmail Edition's web interface -
      the default values stored in each applications ``config/prefs.php`` file
      will be used.

   b. Mcrypt support ``--with-mcrypt``

      Mcrypt is a general-purpose cryptography library which is broader and
      significantly more efficient (FASTER!) than PHP's own cryptographic
      code. You can obtain mcrypt from

         http://mcrypt.sourceforge.net/

      Building PHP without mcrypt support will not stop Horde Groupware
      Webmail Edition from working, but will force it to use weaker (and much
      slower) encryption.

   c. UTF-8 support ``--with-iconv --enable-mbstring=all --enable-mbregex``

      If these extensions are enabled, Horde can support multibyte character
      sets like UTF-8 (meaning that content with any charset can be viewed
      with any translation).

      For iconv support you should use the GNU libiconv library, which is more
      stable and supports more charsets, compared to other iconv
      implementations, like Solaris', for example.

   d. GD support ``--with-gd``

      Horde Groupware Webmail Edition will use the GD extension to perform
      manipulations on image data through the Horde_Image library.

      If you want GD to be able to work with PNG images, you should use the
      ``--with-png-dir`` option to make sure PHP can find the PNG libraries
      it needs to compile.

      If you want GD to be able to work with JPEG images, you should use the
      ``--with-jpeg-dir`` option to make sure PHP can find the JPEG libraries
      it needs to compile.

      You can also use the ImageMagick_ package to do these manipulations
      instead.  See the ``Image Manipulation`` tab of the Horde setup for more
      details.

      .. _ImageMagick: http://www.imagemagick.org

   e. MIME Magic support ``--with-mime-magic``

      Horde Groupware Webmail Edition will use the MIME Magic extension to
      guess the MIME type of files by analyzing their contents.

      .. Note:: This extension is reported to be deprecated_ in favor of the
                fileinfo PECL extension (see below).  However, some users have
                reported that the fileinfo extension will not build correctly
                on their system. If so, than the MIME Magic extension should
                be used instead. Pick one or the other - there is no need to
                compile both.

      If using PHP 4.3.0 -> 4.3.1, you should use ``--enable-mime-magic``
      instead of ``--with-mime-magic``.

      .. _deprecated: http://www.php.net/mime_magic

.. _`OpenSSL Support`:

   f. OpenSSL support ``--with-openssl``

      The OpenSSL PHP extension is used by Horde Groupware Webmail Edition to
      provide S/MIME support.  Without the extension, all S/MIME options will
      be disabled.

      Additionally, the OpenSSL PHP extension is REQUIRED if using TLS or SSL
      to connect to the IMAP/POP3 server.

      See http://www.php.net/openssl for information on compiling OpenSSL
      into PHP.

   g. tidy ``--with-tidy`` (PHP 5+ only)

      The tidy PHP extension is required if you want Horde Groupware Webmail
      Edition to sanitize the output of HTML messages before displaying to the
      user and if you want to clean and repair outgoing HTML messages composed
      via the HTML composition mode.  See ``imp/config/mime_drivers.php.dist``
      for further instructions on how to enable this feature.

4. Additional PECL Modules

   PECL is short for "PHP Extension Community Library".  The goal of PECL is
   to provide a means of easily distributing PHP extensions.

   For more information, see http://pecl.php.net/

   When you install a PECL extension, you have to add it to your ``php.ini``
   so it gets loaded.  Add the following line to your ``php.ini`` file to load
   the extension (the extension should be installed in the directory specified
   by the ``extension_dir`` option in ``php.ini``)::

     extension=fileinfo.so

   Or on Windows::

     extension=fileinfo.dll

   After that, restart your webserver.

   These PECL modules are **RECOMMENDED** to be installed:

   a. fileinfo

      Allows Horde Groupware Webmail Edition modules to guess the MIME type of
      files by analyzing their contents.

      If not enabled, Horde Groupware Webmail Edition will use its own PHP
      code to perform MIME magic lookups. However, this lookup is slower,
      less accurate, and detects fewer MIME types than the PECL extension
      will.

      To install, enter the following at the command prompt::

        pecl install fileinfo

   b. json

      The json extension will be used for JSON serialization if available.
      json's author claims this module is 86 - 270 times faster than a pure
      PHP solution.

      THE JSON MODULE IS ONLY REQUIRED FOR VERSIONS OF PHP < 5.2. JSON
      SUPPORT IS AUTOMATICALLY INCLUDED IN PHP 5.2+.

      To install, enter the following at the command prompt::

        pecl install json

   These PECL modules are **RECOMMENDED** to be installed if you need
   advanced functionality:

   a. memcache

      If using the memcached SessionHandler, the memcache PECL extension must
      be installed.

      To install, enter the following at the command prompt::

        pecl install memcache

   b. lzf

      If the lzf module is available, Horde can compress some cached data in
      the current session, thus reducing the size of the current session.

      THE JSON MODULE IS ONLY REQUIRED FOR VERSIONS OF PHP < 5.2. JSON
      SUPPORT IS AUTOMATICALLY INCLUDED IN PHP 5.2+.

      To install, enter the following at the command prompt::

        pecl install lzf

   c. idn

      idn is required in order to handle Internationalized Domain Names
      (see RFC 3490).

5. At least one IMAP or POP3 server.

   While Horde Groupware Webmail Edition 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 Outlook, Apple Mail or Thunderbird. You must have access to
   an IMAP or POP3 server(s) on which your users' mail is stored in order to
   use Horde Groupware Webmail Edition.

   IMAP is *strongly* recommended over POP3. See, e.g.,
   http://www.imap.org/imap.vs.pop.brief.html

   Freely available IMAP servers (for \*nix systems) that have been verified
   to work with Horde Groupware Webmail Edition include:

   - Courier-IMAP (http://www.inter7.com/courierimap.html)
   - Cyrus (http://asg.web.cmu.edu/cyrus/)
   - Dovecot (http://www.dovecot.org/)
   - UW-IMAP (ftp://ftp.cac.washington.edu/imap/)


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

1. Sendmail or equivalent.

   Horde Groupware Webmail Edition 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 Groupware Webmail Edition to
   speak directly with a remote SMTP server, but this may incur a performance
   penalty.

2. aspell - Spelling Checker

   Aspell, a comand-line program, is used as IMP's spell-checking engine.
   You must install and configure aspell to use IMP's spell-check feature.

   Version 0.60 or higher is REQUIRED.

   You can obtain aspell from:

      http://aspell.sourceforge.net/


Installing Horde Groupware Webmail Edition
==========================================

Horde Groupware Webmail Edition 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 Groupware Webmail Edition, install it directly under the root of your
webserver's document tree.

Since Horde Groupware Webmail Edition 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. Please note that the default configuration expects Horde
to be installed in the directory ``/horde`` though. 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-webmail-x.y.z.tar.gz
   mv horde-webmail-x.y.z horde

You would then find Horde Groupware Webmail Edition at the URL::

   http://your-server/horde/


Configuring Horde Groupware Webmail Edition
===========================================

1. Configuring the web server

   Horde Groupware Webmail Edition 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

      .. Note:: The above instructions may not work if you have specified PHP
                as an output filter with ``SetOutputFilter`` directive in
                Apache 2.x versions.  In particular, Red Hat 8.0 and above
                Apache 2.x RPMS have the output filter set, and **MUST NOT**
                have the above ``AddType`` directive added.

   b. ``index.php`` as an index file (brought up when a user requests a URL for
      a directory)::

         DirectoryIndex index.php

2. Creating databases and Configuring Horde Groupware Webmail Edition

   To configure Horde Groupware Webmail Edition and create the required
   databases run the setup script from the ``scripts/`` directory::

      ./scripts/setup.php

   If you are installing Horde Groupware Webmail Edition on a Windows system,
   or get an error message similar to ``./horde/scripts/setup.php:
   /usr/bin/php: bad interpreter: file or directory not found``, make sure
   that you have a command line version of PHP installed and use it to run the
   script::

      /usr/local/bin/php ./scripts/setup.php

   .. Note:: When you are asked to provide an administrator name during the
             setup, please enter an **existing** IMAP user. You cannot create
             new users or a separate administrator account with the setup
             script.

   If for some reason, creating the databases with ``setup.php`` fails, you
   can create the Horde databases manually.

   First, look in ``scripts/sql/`` to see if a ``groupware.`` script already
   exists for your database. If so, you should be able to simply execute that
   script as superuser in your database. Consult the ``scripts/sql/README``
   file for more information.

   Be sure to change the default database user name and password in this
   script to something else before creating the tables! Use the same password
   that you entered while running ``setup.php``.

   If such a script does not exist, you'll need to build your own, using the
   file ``groupware.sql`` as a starting point. If you need assistance in
   creating databases for a database for which no ``groupware.`` script
   exists, you may wish to let us know on the `Horde mailing list`_.

   .. _`Horde mailing list`: horde@lists.horde.org

3. Setting up alarm emails

   If you want your users to be able to receive emails from the Horde_Alarm
   system, you must set up a cron entry for ``horde/scripts/alarms.php``, you
   must have at least one administrator specified in the Horde configuration,
   and you must have the PHP CLI installed (a CGI binary is not supported -
   ``php -v`` will report what kind of PHP binary you have).

   Running the job every 5 minutes is recommended::

      # Horde Alarms
      */5 * * * * /usr/bin/php /var/www/horde/scripts/alarms.php

   (replace ``/usr/bin/php`` with the path to your PHP CLI and
   ``/var/www/horde/`` with the path to your Horde installation)

4. Testing Horde Groupware Webmail Edition

   Once you have configured your webserver, PHP, and Horde Groupware Webmail
   Edition, bring up the included test page in your web browser to ensure that
   all necessary prerequisites have been met. If you installed Horde Groupware
   Webmail Edition as described above, the URL to the test page would be::

      http://your-server/horde/test.php

   Check that your PHP version is 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.

   If you get a warning like ``Failed opening '/path/to/test.php' for
   inclusion``, make sure that the web server has the permission to read the
   ``test.php`` file.

5. Completing Configuration

   If the IMAP server, that you want to access with Horde Groupware Webmail
   Edition, is not installed on the same server, open the configuration file
   ``imp/config/servers.php`` and change the ``server`` setting in the example
   configuration to the IP address or host name of your IMAP server.

   You can now access Horde Groupware Webmail Edition with the user that you
   specified during the setup, and you will be logged in as an administrator.
   You can click on ``Setup`` in the ``Administration`` menu and configure
   more details of Horde Groupware Webmail Edition.

6. Securing Horde Groupware Webmail Edition

   a. Global Passwords

      Some of Horde Groupware Webmail Edition's configuration files contain
      passwords which local users could use to access your database.  It is
      recommended to ensure that at least the Horde Groupware Webmail Edition
      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 Groupware Webmail Edition'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. User Passwords

      There are two channels by which, unless steps are taken to avoid it,
      Horde Groupware Webmail Edition 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 Horde Groupware Webmail Edition 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 Horde
      Groupware Webmail Edition to connect to the IMAP or POP3 server on
      ``localhost`` instead of on the Internet hostname. This is the default
      setup. 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 Horde Groupware Webmail Edition.

   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.

      Additionally, you can change the session handler of PHP to use any
      storage backend requested (e.g. SQL database) via the ``Custom Session
      Handler`` tab in the Horde setup.

   For more information about securing your webserver, PHP and Horde Groupware
   Webmail Edition, see the `docs/SECURITY`_ file.

7. Entering the survey

   If you like, go to http://www.horde.org/survey/ and enter the details of
   your system.


Temporary Files
===============

Various Horde Groupware Webmail Edition applications will generate temporary
files in PHP's temporary directory (see the ``General`` tab in the Horde
setup).  For various reasons, some of these files may not be removed when the
user's session ends. To reclaim this disk space, it may be necessary to
periodically delete these old temporary files.

An example cron-based solution can be found at ``scripts/temp-cleanup.cron``.
Another possible solution is to use Red Hat's ``tmpwatch`` utility or anything
similar to remove old files (see http://www.redhat.com/).


Translations
============

Note for international users: Horde Groupware Webmail Edition 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), see the
``horde/po/README`` file, or if you're having trouble using a provided
translation, please see the `horde/docs/TRANSLATIONS`_ file for instructions.


Obtaining Support
=================

If you encounter problems with Horde Groupware Webmail Edition, 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 information can be found at

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

There is no separate mailing list for Horde Groupware Webmail Edition, please
contact the mailing list of the component you have problems with, or the Horde
mailing list for general problems and questions.

Lastly, Horde developers, contributors and users may also be found on IRC,
on the channel #horde on the Freenode Network (irc.freenode.net).

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

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

Thanks for using Horde Groupware Webmail Edition!

The Horde Team


.. _README: ?f=README.html
.. _docs/SECURITY: ?f=SECURITY.html
.. _`horde/docs/TRANSLATIONS`: ?f=TRANSLATIONS.html
.. _`File Uploads`: http://wiki.horde.org/FAQ/Admin/FileUploads
