Customizing Horde Groupware Webmail Edition
This document explains how cPanel updates Horde Groupware Webmail, and how you can customize your Horde Groupware Webmail installation.
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 (
) runs, it executes the webmail script found at
. This, in turn, executes
script then does the following:
- Removes the existing Horde installation (via the command
rm -rf /usr/local/cpanel/base/horde).
- Using the version specified in
update-horde, extracts the appropriate Horde source tarball to
- Changes ownership of the Horde installation to the user
root and the group
- Extracts configuration values for maildir, mbox and MySQL from the system settings.
- Backs up the MySQL Horde database to
- Please note that only 4 copies of the Horde database backup are retained in
- Drops the Horde database from MySQL.
- Updates the Horde configuration files and Horde database SQL files with the server's settings.
- Recreates the Horde database from the provided SQL files.
- 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
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-3.1.3p4-local.tar.gz exist, the latter will be used, assuming its version number is specified in the
- The value represented by
$hordever must match the
hordever variable defined in
update-horde. Thus, in
hordever='3.1.3p4', the custom tarball should be named
- 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
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
— but starts with only
After determining which tarball to use for the source install, and extracting it, the
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
Preventing cPanel from modifying the Horde configuration files
Immediately after step 3 in the General Installation Procedure above, and before step 4,
checks for the existence of
- 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.
/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.
Because the SQL data backup performed by
only retains the last 4 backups, continuous execution of
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.