====================================
Installing the Horde 3.3 Framework
====================================
:Last update: $Date: 2009/04/04 12:30:52 $
:Revision: $Revision: 1.90.6.23 $
:Contact: horde@lists.horde.org
.. contents:: Contents
.. section-numbering::
This document contains instructions for installing the Horde Framework on your
system.
The Horde Framework, by itself, does not provide any significant end user
functionality; it provides a base for other applications and tools for
developers. When you have installed Horde as described below, you will
probably want to install some of the available Horde applications, such as
IMP_ (a webmail client), or Kronolith_ (a calendar). There is a list of Horde
applications and projects at http://www.horde.org/projects.php.
If you are interested in developing applications for Horde, there is developer
documentation and references available at http://dev.horde.org/, and some
tutorials and papers on Horde available at http://www.horde.org/papers/.
For information on the capabilities and features of Horde, see the file
README_ in the top-level directory of the Horde distribution.
.. _IMP: http://www.horde.org/imp/
.. _Kronolith: http://www.horde.org/kronolith/
Obtaining Horde
===============
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/
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 PHP files which can be unpacked using
``tar`` and ``gunzip`` (see `Installing Horde`_, below).
Bleeding-edge development versions of Horde and its applications are available
via CVS; see the file `docs/HACKING`_, or visit the website
http://www.horde.org/source/, for information on accessing the Horde CVS
repository.
You will probably also want one or more Horde applications, since Horde
doesn't do much by itself; a list of available applications, with links to
descriptions and downloads, can be found at
http://www.horde.org/projects.php
While previous versions of Horde were numbered to correspond with a particular
version of the IMP webmail application, that is no longer true as of Horde
version 2.0. The current version of Horde will work with the current version
of Horde applications. For more information about which versions are
compatible see http://www.horde.org/source/versions.php.
Quick Install
=============
These are very terse instructions how to install Horde 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|--with-ldap]
make
make install
2. Restart Apache.
3. Install PEAR packages::
pear install -o Log Mail Mail_Mime DB Date File
pear -d preferred_state=beta install -a Services_Weather
4. Extract tarball::
cd /usr/local/apache/htdocs
tar zxvf /path/to/horde-x.y.z.tar.gz
mv horde-x.y.z horde
5. Configure Horde::
cd config/
for f in *.dist; do cp $f `basename $f .dist`; done
6. Create database tables::
cd ../scripts/sql
vi create.mysql.sql
mysql -u root -p < create.mysql.sql
7. Test Horde::
http://your-server/horde/test.php
8. Finish configuration::
http://your-server/horde/
Go to Adminstration => Setup => Horde
Prerequisites
=============
The following prerequisites are **REQUIRED** for Horde to function properly.
1. A webserver that supports PHP.
Horde and its applications are developed under the Apache webserver, which
we recommend. Apache is available from
http://httpd.apache.org/
Horde 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 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 (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 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'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
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:
a. A preferences container.
Horde applications can store user preferences in an SQL database, an
LDAP directory, an IMSP server, a Kolab server, or in PHP sessions.
For SQL database preferences storage, Horde 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, 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'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 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 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 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, then 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
.. Important:: Additionally, individual Horde applications may **REQUIRE**
or **RECOMMEND** other options to be built into PHP
also. Please check ``docs/INSTALL`` for all applications you
wish to use to see if other PHP options are needed.
3. Additional PEAR Modules
PEAR is short for "PHP Extension and Application Repository". The goal of
PEAR is to provide a means of distributing reusable code.
For more information, see http://pear.php.net/
.. Important:: Make sure you are running a supported (i.e. new enough)
version of PEAR: use the test script described below under
"`Configuring Horde`_". Do **not** use the PEAR version
from ftp.horde.org.
Check that the path where the PEAR packages are installed are part of the
``include_path`` parameter that PHP uses to find PEAR packages.
Run the command::
pear config-show
You will see something like::
PEAR directory php_dir /usr/share/php
Now open the php.ini file of your system, for example ``/etc/php.ini``,
find the ``include_path`` and make sure that ``/usr/share/php`` is part of
the list. If you had to change that value, restart the web server after
saving ``php.ini``.
These PEAR modules are **REQUIRED** to be installed for complete Horde
functionality:
a. Log
b. Mail
c. Mail_Mime
To install, enter the following at the command prompt::
pear install Log Mail Mail_Mime
These PEAR modules are **RECOMMENDED** to be installed:
a. DB (>= 1.7.8)
**REQUIRED** as soon as you want or need to store anything in a database.
To install, enter the following at the command prompt::
pear install DB
To upgrade, enter the following at the command prompt::
pear upgrade DB
b. File
**REQUIRED** only if you wish to import CSV files.
To install, enter the following at the command prompt::
pear install File
c. Date
**REQUIRED** only if you are dealing with calendar data.
To install, enter the following at the command prompt::
pear install Date
d. Services_Weather (>= 1.3.1)
**REQUIRED** only if you wish to use the weather.com block on the portal
page.
To install, enter the following at the command prompt::
pear install -a Services_Weather
Additional steps are required if you want use the METAR weather block on
the portal page. See the file ``data/Services_Weather/buildMetarDB.php``
in your PEAR directory for details.
e. HTTP_WebDAV_Server
**REQUIRED** only if you want to use Horde's WebDAV interface, for
example to access calendars, tasklists or files with an external client.
To install, enter the following at the command prompt::
pear install HTTP_WebDAV_Server-beta
f. Net_DNS
If installed, it will be used instead of the built-in PHP function
gethostbyaddr() for host name lookups. This has the advantage that
Net_DNS has configurable timeouts and retries. Net_DNS requires the
``mhash`` PHP extension.
To install, enter the following at the command prompt::
pear install Net_DNS
This method of installing PEAR modules requires that you have a PHP version
that has been compiled as a static binary. All versions of PHP 4.3.0+
build both a SAPI module (Apache, CGI, etc.) and a command-line (CLI)
binary at the same time. Check if you have a php binary in
``/usr/local/bin`` (``/usr/bin`` if if you installed from an operating
system package) before recompiling.
If you receive the error ``Could not read cmd args`` you should run the pear
script this way::
php -d register_argc_argv=1 _PEAR_ install _MODULE_
_PEAR_ is the complete path of the pear script installed by PHP during
installation (e.g. ``/usr/local/bin/pear``). Make sure the ``pear`` script
appears in your path. The default installation path for pear is
``/usr/local/bin/pear``.
_MODULE_ is the PEAR module, listed above, which you wish to install.
For more detailed directions on installing PEAR modules, see the PEAR
documentation at http://pear.php.net/manual/
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/
PECL is the "sister" of PEAR and uses the same packaging and distribution
system as PEAR, so the configuration/setup is essentially identical to the
PEAR instructions above.
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 modules to guess the MIME type of files by analyzing
their contents.
If not enabled, Horde 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.
To install, enter the following at the command prompt::
pecl 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 application (as noted in [brackets]):
1. Sendmail or equivalent.
Horde 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 to speak directly with a remote SMTP server, but this
may incur a performance penalty.
Installing Horde
================
Horde 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, install it directly
under the root of your webserver's document tree.
Installing from Release Tarballs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Since Horde 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-x.y.z.tar.gz
mv horde-x.y.z horde
You would then find Horde at the URL::
http://your-server/horde/
Skip the next paragraph if you installed Horde from a release tarball.
Installing from CVS or Snaphots
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At this point, the Horde framework modules need to be checked out from CVS and
installed. This must be done as root (or another user with sufficient
administrator priviledges)::
cd horde
cvs co framework
cd framework
pear channel-discover pear.horde.org
php -q install-packages.php
For Windows systems - use the ``install-packages.bat`` file instead.
For Debian systems - the command-line PHP interpreter might be called ``php4``
instead of ``php``.
.. Note:: You need PEAR version 1.4.0 or higher to run the install scripts.
Configuring Horde
=================
1. Configuring the web server
Horde 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
The specific steps to create a preferences storage container depend on
which database you've chosen to use.
First, look in ``scripts/sql/`` to see if a ``create.`` 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 password, ``horde``, to something else before
creating the tables! (Remember to use this password when you configure
Horde in the next step.)
If such a script does not exist, you'll need to build your own, using the
files ``horde_users.sql``, ``horde_prefs.sql``, and ``horde_datatree.sql``
as a starting point. If you need assistance in creating databases for a
database for which no ``create.`` script exists, you may wish to let us
know on the `Horde mailing list`_.
If you make any changes to the user that will access the database,
you **MUST** ensure that that user can still create
tables. Otherwise Horde will be unable to create sequence tables
for tracking primary keys.
If you are going to use database based sessions, create a table using the
files ``scripts/sql/horde_sessionhandler*.sql`` as a starting point.
.. _`Horde mailing list`: horde@lists.horde.org
3. Configuring Horde
To configure Horde, 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 f in *.dist; do cp $f `basename $f .dist`; done
Or if you are installing Horde an a Windows system::
cd config
copy *.dist *.
Documentation on the format of those files can be found in each file.
.. Warning:: All configuration files in Horde 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.php for example run::
php -l mime_drivers.php
4. 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)
5. Testing Horde
Once you have configured your webserver, PHP, and Horde, bring up the
included test page in your Web browser to ensure that all necessary
prerequisites have been met. If you installed Horde as described above, the
URL to the test page would be::
http://your-server/horde/test.php
Check that your PHP and PEAR versions are 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.
6. Completing Configuration
You can now access Horde without a password, and you will be logged in as
an administrator.
.. Important:: You should first configure a real authentication
backend and designate which accounts in your real
backend will be administrator accounts. Horde does
**NOT** have a default administrator account - all
users, including administrators, must exist in the
actual authentication backend. Click on ``Setup``
in the ``Administration`` menu and configure Horde.
Start in the ``Authentication`` tab.
Here is an example for configuring authentication against a remote IMAP
server. Similar steps apply for authenticating against a database, an LDAP
server, etc.
a. In the ``Which users should be treated as administrators`` field enter a
comma separated list of user names of your choosing. This will control
who is allowed to make configuration changes, see passwords, potentially
add users, etc.
b. In the ``What backend should we use for authenticating users to Horde``
pulldown menu select ``IMAP authentication``. The page will reload and
you will have specific options for IMAP authentication.
c. In the ``Configuration type`` pulldown menu select ``Separate values``.
The page will reload with additional options. Fill in the remaining
three fields appropriately:
- IP name/number of the IMAP server
- For a secure connection, select port 993.
- Select the protocol; for a secure connection either ``imap/ssl`` or
``imap/ssl/novalidate-cert`` (for self-signed certificates).
Continue to configure Horde through all the tabs of the setup interface and
click on ``Generate Horde Configuration``. Important items that you
probably want to configure are the ``Preference System`` that lets users
save their personal options, and the ``DataTree System`` that is required
for some applications to work at all.
Configuration of applications in ``registry.php`` is documented in the
``INSTALL`` file of each application. Most applications require you to
configure them with a "Horde administrator" account. A Horde administrator
account is any normal Horde account that has been added to the
administrator list in the ``Authentication`` tab of the Horde setup.
The other files in that directory need only be modified if you wish to
customize Horde's appearance or behaviour -- the defaults will work at most
sites.
7. Securing Horde
a. Passwords
Some of Horde's configuration files contain passwords which local users
could use to access your database. It is recommended to ensure that at
least the Horde 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'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.
8. Entering the survey
If you like, go to http://www.horde.org/survey/ and enter the details of
your system.
Configuring Applications
========================
A list of available Horde applications can be found at
http://www.horde.org/projects.php
Instructions on configuring Horde applications can be found in the ``INSTALL``
file in the application's ``docs/`` directory.
Temporary Files
===============
Various Horde 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 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, 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/
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 is free software written by volunteers.
For information on reasonable support expectations, please read
http://www.horde.org/support.php
Thanks for using Horde!
The Horde Team
.. _README: ?f=README.html
.. _docs/HACKING: ?f=HACKING.html
.. _docs/SECURITY: ?f=SECURITY.html
.. _`horde/docs/TRANSLATIONS`: ?f=TRANSLATIONS.html
