Customizing Horde Groupware Webmail Edition

This document explains how cPanel updates Horde Groupware Webmail, and how you can customize your Horde Groupware Webmail installation.

Important: These methods for customizing Horde allow you full control over the end user experience. However, such customizations fall outside the range of support cPanel offers.

General Installation Procedure

Before you customize your Horde installation, it is useful to understand how cPanel updates Horde.

When the cPanel update script (/scripts/upcp) runs, it executes the webmail script found at /usr/local/cpanel/install/webmail. This, in turn, executes /usr/local/cpanel/bin/update-horde.

The update-horde script then does the following:

1. Removes the existing Horde installation (via the command rm -rf /usr/local/cpanel/base/horde).
2. Using the version specified in update-horde, extracts the appropriate Horde source tarball to /usr/local/cpanel/base.
3. Changes ownership of the Horde installation to the user root and the group wheel.
4. Extracts configuration values for maildir, mbox and MySQL from the system settings.
5. Backs up the MySQL Horde database to /var/cpanel/horde/horde.backup.sql.«current timestamp».
   • Please note that only 4 copies of the Horde database backup are retained in /var/cpanel/horde.
6. Drops the Horde database from MySQL.
7. Updates the Horde configuration files and Horde database SQL files with the server's settings.
8. Recreates the Horde database from the provided SQL files.
9. Reloads the previous Horde database backup, finishing the Horde update.

Installing a Customized Instance of Horde

There are several ways to customize the Horde installation. Options range from making simple configuration changes to completely replacing the cPanel-supplied Horde tarball.

For instructions on customizing Horde, see the Horde wiki.

Where to place a custom Horde tarball

During step 2 of the General Installation Procedure above, the update-horde script checks for custom Horde tarballs in the following locations:

• /var/cpanel/horde/horde-local.tar — Use this location for an uncompressed tarball you want to apply to Horde regardless of version.
• /var/cpanel/horde/horde-local.tar.gz — Use this location for a compressed tarball you want to apply to Horde regardless of version.
• /var/cpanel/horde/horde-$hordever-local.tar — Use this location for an uncompressed tarball you want to apply to a specific Horde version.
• /var/cpanel/horde/horde-$hordever-local.tar.gz — Use this location for a compressed tarball you want to apply to a specific Horde version.

If any of those tarballs exist, they are used in lieu of the tarball supplied by cPanel.

• If the script locates multiple tarballs, it will use the one furthest down the list above.
  • For example, if both /var/cpanel/horde/horde-local.tar and /var/cpanel/horde/horde-3.1.3p4-local.tar.gz exist, the latter will be used, assuming its version number is specified in the update-horde script.
• The value represented by $hordever must match the hordever variable defined in update-horde. Thus, in update-horde, if hordever='3.1.3p4', the custom tarball should be named horde-3.1.3p4-local.tar.gz.
• As with the tarball supplied by cPanel, these tarballs must extract to a directory named horde, all lowercase and without a version number.
  • The end result is the directory /usr/local/cpanel/base/horde

Where to place a custom overlay file

The overlay tarball provides a simple way of customizing specific aspects of Horde. For example, you can use an overlay to change graphics, themes, modules, plugins and the like.

The overlay need not contain a complete Horde distribution. It only needs to contain the components to be modified, since it will be "overlaid" onto the Horde installation. The overlay can contain 1 image file, for example.

It does, however, need to contain a directory structure that mimics /usr/local/cpanel/base/horde — but starts with only horde.

After determining which tarball to use for the source install, and extracting it, the update-horde script checks for the following:

• /var/cpanel/horde/overlay.tar — Use this location for an uncompressed overlay you want to apply to Horde regardless of version.
• /var/cpanel/horde/overlay.tar.gz — Use this location for a compressed overlay you want to apply to Horde regardless of version.
• /var/cpanel/horde/overlay.$hordever.tar — Use this location for an uncompressed overlay you want to apply to a specific Horde version.
• /var/cpanel/horde/overlay.$hordever.tar.gz — Use this location for a compressed overlay you want to apply to a specific Horde version.

As with the custom Horde tarballs above,

• If the script locates multiple tarballs, it will use the one furthest down the list.
• The value of $hordever must match the version number specified in the update-horde script.

Preventing cPanel from modifying the Horde configuration files

Immediately after step 3 in the General Installation Procedure above, and before step 4, update-horde checks for the existence of /var/cpanel/horde/install.

• If that file exists and is executable, the update-horde script will execute it and terminate, thus bypassing cPanel's manipulation of the Horde configuration files.
  • In this case, steps 4 – 9 of the General Installation Procedure do not occur.
• If /var/cpanel/horde/install exists but is not executable, the file contents will be printed to STDOUT and the normal cPanel configuration of Horde will continue with the remaining steps detailed in the General Installation Procedure.

Warning: Because the SQL data backup performed by update-horde only retains the last 4 backups, continuous execution of update-horde may cause you to lose all your customer data (unless it is retained in external backups). For this reason, we do not advise continuous backups of a non-operational Horde installation.