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

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


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

     cd php-x.x.x/
     ./configure --with-apxs2=/usr/sbin/apxs2 \
                 --with-gettext --enable-mbstring=all --enable-mbregex \
                 --with-gd --with-png-dir=/usr --with-jpeg-dir=/usr \
                 [--with-mysql|--with-pgsql|--with-oci8]
                 [--with-tidy]
                 [--with-ftp]
     make
     make install

2. Restart Apache.

3. Register Horde PEAR channel::

     pear channel-discover pear.horde.org

4. Set Horde installation directory::

     pear install horde/horde_role
     pear run-scripts horde/horde_role

5. Install Horde Groupware::

     pear install -a -B horde/groupware

6. Run installation script::

     groupware-install

7. Test Horde Groupware::

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


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

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

1. A webserver that supports PHP.

   Horde Groupware is primarily developed under the Apache and Lighttpd
   webservers, which we recommend.  These servers are available from:

      http://httpd.apache.org/
      http://www.lighttpd.net/

2. A web server with PATH_INFO support.

   The dynamic interfaces of Horde Groupware 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 5.3.0 or above.

   PHP is the interpreted language in which Horde Groupware is written.

   .. Note:: If possible, you should install PHP with your operating system's
             package manager. Alternatively you build PHP yourself.

   To build PHP from sources, you can obtain it 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.

      XML and DOM support are enabled in PHP 5 by default. You only have to
      make sure that you do **not** use ``--disable-dom``,
      ``--disable-simplexml``, or ``--disable-xml``.

      Make sure you are using a newer version of libxml.  Older version of
      libxml (e.g. 2.6.26) have been reported to be partially broken when
      handling certain charsets.

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

   a. File Upload Support

      File upload support is **required** to allow various importing features
      to work. 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 and will not be available to the
       user.

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

   b. 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(i) (``--with-mysql(i)``) and PostgreSQL
      (``--with-pgsql``), and has been reported to work with SQLite (enabled by
      default).

      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.

   c. UTF-8 support (mbstring and iconv extensions) ``--enable-mbstring``

      If these extensions are enabled, Horde Groupware can better support
      multibyte character sets like UTF-8.

      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.

      Iconv support is enabled by default in PHP 5. You only have to make sure
      that you do **not** use ``--without-iconv``

   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 imagick_ extension or the ImageMagick_ package to do
      these manipulations instead. The imagick_ extension is the recommended
      method for image manipulation. See the ``Image Manipulation`` tab of the
      Horde configuration for more details.

      .. _imagick: http://pecl.php.net/package/imagick
      .. _ImageMagick: http://www.imagemagick.org

   e. tidy ``--with-tidy``

      The tidy PHP extension is required to sanitize HTML data.

.. _`OpenSSL Support`:

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

      The OpenSSL PHP extension is used by Horde Groupware 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 a server.

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

   g. fileinfo

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

      This module is automatically enabled by default.

   h. intl ``--enable-intl``

      The intl module is required to handle display of Internationalized
      Domain Names (see RFC 3490), e.g in e-mail addresses.

   i. FTP support ``--with-ftp``

      If using the FTP VFS driver for the file manager, the FTP PHP module is
      **required**.

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 if you need
   advanced functionality:

   a. imagick

      The imagick module can be used by Horde's image library to provide all
      kind of image manipulations.

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

        pecl install imagick

   b. lzf

      If the lzf module is available, Horde Groupware 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::

        pecl install lzf

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

The following non-PHP prerequisites are **RECOMMENDED**:

1. aspell - Spelling Checker

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

   Version 0.60 or higher is REQUIRED.

   You can obtain aspell from:

      http://aspell.sourceforge.net/

2. Sendmail or SMTP server.

   Horde Groupware sends mail via either a local sendmail or a remote SMTP
   server.  It is **RECOMMENDED** that SMTP be used.

3. FTP server.

   If using a FTP backend for the file manager, you **must** have at least one
   FTP server.

4. ElasticSearch server.

   An ElasticSearch_ server or cluster running on localhost can be used to
   provide indexing of bookmarks data and quick searching of the indexed
   content.

.. _ElasticSearch: http://www.elasticsearch.org/


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

The **RECOMMENDED** way to install Horde Groupware is using the PEAR installer.


Installing with PEAR
~~~~~~~~~~~~~~~~~~~~

First you need to register the Horde PEAR channel server to your local PEAR
system. This has to be done only **once** ever on a single PEAR system::

   pear channel-discover pear.horde.org

Next install a so-called "role" for Horde. This role defines where Horde
Groupware is supposed to be installed. This should be a directory in your web
server's web root, e.g. ``/var/www/groupware``. Again this has to be done only
**once** ever on a single PEAR system::

   pear install horde/horde_role
   pear run-scripts horde/horde_role

When installing Horde Groupware through PEAR now, the installer will
automatically install any dependencies of Horde Groupware too. If you want to
install Horde Groupware with all optional dependencies, but without the binary
PECL packages that have to be compiled, specify both the ``-a`` and the ``-B``
flag::

   pear install -a -B horde/groupware

By default, only the required dependencies will be installed::

   pear install horde/groupware

If you want to install Horde Groupware even with all binary dependencies, you
need to remove the ``-B`` flag. Please note that this might also try to install
PHP extensions through PECL that might need further configuration or activation
in your PHP configuration::

   pear install -a horde/groupware


Installing into separate PEAR
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. Warning:: Unless you really know **why** you want to do this, you probably
             do **not** want to do this. Use the general PEAR installation
             instructions from above instead.

If you want to create a separate PEAR installation for installing Horde
Groupware, independent from the system-wide PEAR installation, this can be done
with the following commands (in this example, ``/var/www/groupware`` is used as
the location of the web-accessible Horde directory)::

   mkdir /var/www/groupware
   pear config-create /var/www/groupware /var/www/groupware/pear.conf
   pear -c /var/www/groupware/pear.conf install pear

Then follow the regular installation steps, but use the ``pear`` command from
the PEAR installation you just created, e.g.::

   /var/www/groupware/pear/pear -c /var/www/groupware/pear.conf \
       channel-discover pear.horde.org

Finally configure your web server in some way to point PHP's ``include_path``
setting to the PEAR installation and the ``PHP_PEAR_SYSCONF_DIR`` environment
variable to the directory used during the config-create command::

   php_value include_path /var/www/groupware/pear/php
   SetEnv PHP_PEAR_SYSCONF_DIR /var/www/groupware

It is recommended to not use the .htaccess file in ``/var/www/groupware/`` to
set these values because it will be overwritten with every further update.


Finishing installation
~~~~~~~~~~~~~~~~~~~~~~

To finish installation, run the installation script on the command line and
answer all questions::

   groupware-install

If you installed Horde Groupware into the global PEAR system, this script
should be in your command path. If the script cannot be found in your path, you
need to specify the full path to the script, e.g.::

   /var/www/groupware/pear/groupware-install

You can use the ``pear`` command to find the place where the script has been
installed::

   pear config-get bin_dir

If you installed into a local PEAR installation, you need to tell PHP and PEAR
where to find the installation and the script, e.g.::

   PHP_PEAR_SYSCONF_DIR=/var/www/groupware php \
       -d include_path=/var/www/groupware/pear/php \
       /var/www/groupware/pear/groupware-install


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

   c. If you plan to provide ActiveSync support to your users, you have to
      create an alias of the ``/Microsoft-Servers-ActiveSync`` URL to
      ``/groupware/rpc.php``. See http://wiki.horde.org/ActiveSync for details.

2. Configuring Horde Groupware

   Documentation on the format and purpose of the configuration files in the
   ``config/`` directory can be found in each file. The defaults will be
   correct for most sites. If you wish to customize Horde Groupware's
   appearance and behavior, create "local" files for the configuration file you
   want to change. For example if you want to change the default value and lock
   a preference, create a ``config/prefs.local.php`` file with the following
   content::

      <?php
      $_prefs['prefname']['value'] = 'somedefault';
      $_prefs['prefname']['locked'] = true;

   This works with any configuration file.

   .. Warning:: All configuration files in Horde Groupware are PHP scripts that
                are executed by the web server. If you make an error in one of
                these files, Horde might stop working. Thus it is always a good
                idea to test the configuration files after you edited them. If
                you want to test mime_drivers.local.php for example run::

                   php -l mime_drivers.local.php

   The default configuration stores files uploaded through the file manager in
   the SQL database. This is the most compatible configuration but doesn't
   scale well, may hit some database server limits, and may only work for very
   small installations. You should configure a different backend as soon as
   possible. See ``gollem/config/backends.php`` and
   ``gollem/config/backends.d/10-groupware.php`` for details.

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-alarms``, 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/horde-alarms

   If not installing Horde Groupware through PEAR or if PEAR's ``bin_dir``
   configuration doesn't point to ``/usr/bin/``, replace
   ``/usr/bin/horde-alarms`` with the path to the ``horde-alarms`` script in
   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/groupware/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. Securing Horde Groupware

   a. Global 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 -R root.www config/*
         find config/ -type f -exec chmod 0440 '{}' \;

   b. User Passwords

      Unless steps are taken to avoid it, there are two channels by which Horde
      Groupware can cause users to pass their IMAP/POP3 passwords across the
      network unencrypted.

      The first channel is between the 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 is running. Some sites may wish to disable non-SSL
      access entirely.

      The second channel is between the Web server and their authentication
      backend.  The simplest way to avoid this is to have the authentication
      source running on the same system as the Web server, and configuring
      Horde Groupware to connect to the backend on ``localhost`` instead of on
      the Internet hostname. In cases where that is not possible, it is highly
      recommended that the backend be located on a private, secure network.
      Alternatively, the backend may be accessed via TLS to ensure that users'
      passwords remain safe after they have entrusted them to Horde Groupware
      (this is the default configuration).

      Other security steps you can take to increase security include:

      * Use session cookies instead of URL based sessions.
      * Set your php ``session.entropy_length`` to a larger value (e.g. 16) and
        ``session.entropy_file`` to a random source (e.g. ``/dev/urandom``)
      * If your database, mail server, and web server are on the same host
        machine, then:

        * Use unix socket database access and disable TCP database access.
        * Use ``localhost`` for all TCP/IP connections to avoid the network, or
          run all services on a local, private network.

   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,
   see the `docs/SECURITY`_ file.


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
``horde/scripts/temp-cleanup.cron`` in PEAR's ``data_dir`` directory.  Another
possible solution is to use utilities like ``tmpwatch``, ``tmpreaper`` or
anything similar to remove old files.

Stale sessions are automatically pruned by PHP according to the
`session.gc_probability`_, `session.gc_divisor`_, and
`session.gc_maxlifetime`_ settings located in ``php.ini``. However, the
default settings are very aggressive: the garbage collection routine runs on
average 1% of the time a page is loaded. For most installations, a lower
garbage collection rate is recommended (setting session.gc_divisor to 10,000
or higher is much more reasonable).


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), or if you're having trouble using a provided
translation, please see the `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://wiki.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/community/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/community/support

Thanks for using Horde Groupware!

The Horde Team


.. _README: README
.. _docs/SECURITY: ../../horde/docs/SECURITY
.. _docs/TRANSLATIONS: ../../horde/docs/TRANSLATIONS
.. _`File Uploads`: http://wiki.horde.org/FAQ/Admin/FileUploads
.. _`session.gc_probability`: http://www.php.net/manual/en/session.configuration.php#ini.session.gc-probability
.. _`session.gc_divisor`: http://www.php.net/manual/en/session.configuration.php#ini.session.gc-divisor
.. _`session.gc_maxlifetime`: http://www.php.net/manual/en/session.configuration.php#ini.session.gc-maxlifetime
