================================
 Installing Horde Groupware 1.1
================================

:Last update:   $Date: 2007/11/26 17:50:42 $
:Revision:      $Revision: 1.11 $
:Contact:       horde@lists.horde.org

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

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

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


Obtaining Horde Groupware
=========================

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

   http://www.horde.org/groupware/

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

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 PHP files which can be unpacked
using ``tar`` and ``gunzip`` (see `Installing Horde Groupware`_, below).


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

These are very terse instructions how to install Horde Groupware 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-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-groupware-x.y.z.tar.gz
     mv horde-groupware-x.y.z horde

4. Configure Horde Groupware::

     ./scripts/setup.php

5. Test Horde Groupware::

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

6. Finish configuration::

     http://your-server/horde/

   Go to Adminstration => Setup => Horde


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

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

1. A webserver that supports PHP.

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

      http://httpd.apache.org/

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

2. PHP 4.3.0 or above.

   PHP is the interpreted language in which Horde Groupware 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 (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 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'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 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.

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

   a. A preferences container.

      Horde Groupware 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 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, 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'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 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).

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

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

3. 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 modules to guess the MIME type of files by
      analyzing their contents.

      If not enabled, Horde Groupware 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::

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

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

        pear 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::

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

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

        pear install lzf

   For additional help on using the pear command-line program to install PECL
   extensions, see the PEAR installation section above.


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

1. Sendmail or equivalent.

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


Installing Horde Groupware
==========================

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

Since Horde Groupware 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-groupware-x.y.z.tar.gz
   mv horde-groupware-x.y.z horde

You would then find Horde Groupware at the URL::

   http://your-server/horde/



Configuring Horde Groupware
===========================

1. Configuring the web server

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

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

      ./scripts/setup.php

   If you are installing Horde Groupware 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

   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``, 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

   Once you have configured your webserver, PHP, and Horde Groupware, bring up
   the included test page in your web browser to ensure that all necessary
   prerequisites have been met. If you installed Horde Groupware 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

   You can now access Horde Groupware with the user and password that you
   entered 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.

6. Securing Horde

   a. Passwords

      Some of Horde Groupware'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 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'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. 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, 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 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 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, 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, 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 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!

The Horde Team


.. _README: ?f=README.html
.. _docs/SECURITY: ?f=SECURITY.html
.. _`horde/docs/TRANSLATIONS`: ?f=TRANSLATIONS.html
