================================== INSTALLING THE HORDE 2.2 FRAMEWORK ================================== 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. 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/ The "tarballs/" subdirectory contains the Horde PHP files which can be unpacked using tar+gunzip (see INSTALLING HORDE, below). If you are using Red Hat Linux and prefer to use RPMs, they can be found here: ftp://ftp.horde.org/pub/RPMS/ (For an RPM install, consult the README file in the RPM directory for important instructions!) Bleeding-edge development versions of Horde and its applications are available via CVS; see the file docs/HACKING 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. 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://www.apache.org/ Horde has also been reportedly used successfully under Microsoft IIS in the past. 2. PHP 4.1.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 the --with-apache or --with-apxs 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 support. (--with-xml) Horde's help engine requires 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://www.jclark.com/xml/expat.html The following PHP options are either recommended or are required by a specific Horde application (as noted in [brackets]): c. A preferences container. Horde applications can store user preferences in an SQL database, an LDAP directory, 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-oracle). It may also work with any other database supported by PEAR, but they are untested. Preferences can also be stored via LDAP (--with-ldap). 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 or database server need not be running on the machine onto which you are installing Horde, the appropriate client libraries to access the LDAP or database server must be available locally. d. Mcrypt support (--with-mcrypt) Mcrypt is a general-purpose cryptography library which is broader and more efficient than PHP's own cryptographic code. You can obtain mcrypt from http://mcrypt.hellug.gr/ Building PHP without mcrypt support will not stop Horde from working, but will force it to use weaker encryption. e. [IMP] IMAP and POP3 support (--with-imap) PHP uses the UW-IMAP c-client library to provide IMAP and POP3 support. C-client is available from ftp://ftp.cac.washington.edu/imap/ IMP requires IMAP and POP3 support in PHP. 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/ Horde requires several additional PEAR modules to be installed for complete functionality. a. Log To install, you must enter the following at the command prompt: pear install Log b. Mail_Mime To install, you must enter the following at the command prompt: pear install Mail_Mime c. Net_Socket (optional) This is required if you wish to send mail via SMTP. To install, you must enter the following at the command prompt: pear install Net_Socket This method requires that your PHP has been compiled as a static binary. If you installed PHP as a webserver module, recompile PHP without the module option (for Apache, without --with-apache and --with-apxs) and do a 'make install'. Note that recent versions of PHP (4.3-cvs and greater) 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 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 _URL_ _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'. _URL_ is the URL, listed above, which you wish to download from. For more detailed directions on installing PEAR modules, see the PEAR documentation at http://pear.php.net/manual/ 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. A local sendmail interface is strongy recommended when using IMP. 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. (For an RPM installation, consult the README file in the RPM directory for important instructions! The following instructions are for a tarball installation.) 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. 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-2.2.tar.gz mv horde-2.2 horde and would then find Horde at the URL http://your-server/horde/ 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 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/db/ 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. 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 auth.sql, prefs.sql, and category.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. Note that the "_drop" scripts in the scripts/db/ directory remove the changes made by the "_create" scripts. 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 foo in *.dist; do cp $foo `basename $foo .dist`; done Documentation on the format of those files can be found in each file. You must at least complete the "Preferences System Settings" section of horde.php and provide paths to helper applications in mime_drivers.php. Configuration of applications in registry.php is documented in the INSTALL file of each application. 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. 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), or if you're having trouble using a provided translation, please see the po/README file for instructions. 4. 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. 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. 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. 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 informatoin can be found at http://www.horde.org/mail/ Lastly, Horde developers, contributors and users also make occasional appearances on IRC, on the channel #horde on the Open Projects Network (irc.openprojects.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 horde@lists.horde.org $Horde: horde/docs/INSTALL,v 1.28.2.19 2002/09/13 21:43:07 jan Exp $