Introduction 

As part of the set up of my server I like to install Horde and Imp. Horde is a PHP based web application framework and Imp is an IMAP based web mail client. This article will go through setting thse two applications up and interfacing them with a standard IMAP server - in this case Courier IMAP.

Install PHP5 on Apache 2

Install the Apache 2 packages and libapache2-mod-php5. This will restart your apache server if you already have one installed. It is not necessary to upgrade from Apache 1.x but it is probably worth it. By default PHP is set up to run for development systems and can pose a moderate security threat to the rest of the system therefore a little more work is needed to get the server ready. Move the original PHP configuration file to somewhere else:

mv php.ini php.ini.original 

and put in its place the recommended settings:

cp /usr/share/doc/php5-common/examples/php.ini-recommended ./php.ini 

It is a good idea to make PHP hide the fact it is installed from the rest of the world which is done by setting expose_php =off in /etc/php5/apache2/php.ini. There is no reason to let the world know you have PHP installed so why tell them? In order to use PHP5 on your system you will probably need to remove all the PHP4 packages first. So that the packages that are dependent on PHP don't get removed (phpmyadmin for examples) install the corresponding PHP5 packages and then remove the PHP4 packages. This seems to be quite a round about way of doing things but if the PHP5 packages aren't installed Apache will not process any .php files.

Install Horde and Imp 

Now that PHP is installed install the Horde and Imp packages - this should be a completely painless process. The default install of Horde uses the home directory /usr/share/horde3 which is where you will find the files that run the site.

Create a virtual host for your horde install. The example below is about as simple as you could make it:

<VirtualHost *>
ServerName horde.crazysquirrel.com
DocumentRoot /usr/share/horde3/
ServerAdmin webmaster@crazysquirrel.com
ErrorLog /var/log/apache2/error.log
CustomLog /var/log/apache2/horde.crazysquirrel.com.log combined
Options -Indexes +FollowSymlinks
AllowOverride Limit
DirectoryIndex index.php
</VirtualHost>

In there you will find a file called test.php which can be accessed in a browser via http://www.example.com/test.php where www.example.com is your site address. It's worth noting that I will be installing horde under it's own sub-domain but it can equally be installed under you standard domain and accessed through a special path. If the test reports any missing, optional, PHP modules install them now. In my case I needed to install php5-mcrypt and php5-memcache. 

The test page may also report a problem with the memory limit on the PHP process. This memory  limit is useful for stopping run away processes but it can also stop a valid process that needs to use a moderate amount of memory. The default memory limit is 16MB which is a little on the low side for Imp if you want to be able to send large-ish attachments. If all you are doing is sending plain e-mail this is fine but personally I up the limit to 48MB to be on the safe side. The setting is called memory_limit and is about 30% of the way down the file /etc/php5/apache2/php.ini. 

Configure Horde 

Update the webroot setting in the horde stanza in /etc/horde/horde3/registry.php since I will give horde it's own domain I change it to 'webroot' => '',. Now run the appropriate database script in /usr/share/doc/horde3/examples/scripts/sql. In my case I want to use a PostgresQL database so I will run the create.pgsql.sql script as the postgres user.

su - postgres
cd /usr/share/doc/horde3/examples/scripts/sql
psql -f create.pgsql.sql

This will create a user and database called horde. It is imperative that you change the password for the horde user. This can be done from the command prompt or via an interface such as Webmin. If you want to use database managed sessions run the script horde_sessionhandler.pgsql.sql. Horde is now pretty much ready to go. Note: if you need to change the password for the database connection the setting is in /etc/horde/horde3/conf.php. Search for sql or password.

By default Horde is disabled fur security reasons, to enable it remove the echo and exit( 0 ) directives from top of  /etc/horde/horde3/conf.php. If you want Horde to be able to write it's own configuration files (which is very handy) it is necessary to give the user www-data permission to write files in /etc/horde/horde3. This should be considered a security hole so think before changing the permissions on these files and after everything is configured seriously consider changing the owner back to root.. If you do decide to change the permissions it can be done like this:

cd /etc/horde
chown -R www-data:www-data horde3
chown -R www-data:www-data imp4 

You can now log in as an administrator without a password - a set up which much be changed as soon as possible. This change is effected by setting up a real authentication back end. Pull up the horde site and open Administration in the left menu and select Set Up. Select Horde from the list and then the Authentication tab. I'm going to make myself an administrator and authenticate against my IMAP server which I will do via Imp.

Open the servers.php file and scroll down towards the bottom of it. There you will find a number of example server settings (which IMHO should be commented out) remove all but the IMAP example (normally the first example) and then configure it for your server. Restart Apache and try to log in. Important: if you find that you can't login but upon checking the horde log file /var/log/horde/horde3.log you see a message stating that login was successful you are probably setting the wrong path for the session cookies. The default path found in /etc/horde/horde3/conf.php and should be set to:

$conf['cookie']['path'] = '/'; 

if you are running horde under it's own domain. If you are running horde under another domain enter the path to horde where the / is. Typically this will be something like /horde3.

You should now have a working Horde and Imp installation. It is worth now spending some time playing with the configuration settings to make sure everything is set up as you want it.

Further Configuration 

Now that you have a working Horde installation it is time to tweak it such that it is to you liking. The first thing I do is install a database back preferences system. If you rely on the PHP Sessions preferences system users will have to set their preferences every time they log in as the settings aren't saved anywhere. In the horde sql scripts directory run the file horde_prefs.sql to create the required tables and then change the preference settings through the horde interface. If you haven't already done so you will need to set up the database connection first.