Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Configuration: Load balanced Setup
Clone this wiki locally
Roundcube in a load-balanced multi-server setup
The default config shipped with the Roundcube packages is primarily set to be used on a single host. But Roundcube has capabilities to be run on multiple servers behind a load balancer or reverse proxy to serve a high-performance webmail service. And these are the bits that needs to be adjusted when running multiple front-end servers:
- Database access
- Shared session data storage
- Shared access to attachment uploads
Roundcube uses a database to store user preferences, address books and caches. We recommend to run a dedicated database server (master) which all the Roundcube instances access via TCP. For performance improvements, you can set up replicated slaves on the Roundcube hosts and define two database connections for read and write access in Roundcube's config:
// PEAR database DSN for read/write operations $config['db_dsnw'] = 'mysql://roundcube:********@dbmasterhost/roundcubemail'; // PEAR database DSN for read only operations (if empty write database will be used) $config['db_dsnr'] = 'mysql://roundcube:********@localhost/roundcubemail';
Shared session data storage
By default, Roundcube uses the database to store session data. Thus without further modification this will also work in a multi-server setup with a dedicated database server. Although when replication with local slaves is in place the latency of the replication process can cause unexpected behavior when a Roundcube client reads outdated data from the local slave.
Roundcube therefore provides alternative options for session storage:
memcache or native
php configurable with the
session_storage config option.
Memcached is a distributed caching daemon that can store data in memory redundantly on multiple hosts. In order to use it for session storage in Roundcube you first need to install and configure one or multiple memcache hosts. Then the Memcache extension (version >= 2.0.0) for PHP needs to be installed. You'll find various tutorials describing how to setup memcache with php on the net. Finally, adjust Roundcube's configuration accordingly:
// Backend to use for session storage. Can either be 'db' (default), 'memcache' or 'php' $config['session_storage'] = 'memcache'; // Use these hosts for accessing memcached // Define any number of hosts in the form of hostname:port or unix:///path/to/socket.file $config['memcache_hosts'] = array( 'localhost:11211', '192.168.1.12:11211');
PHP natively allows you to configure different backends for session storage, some of them are designed for sharing session data amongst multiple web servers. While Roundcube by default registers its own session handlers to store sessions in database or memcache, there are cases where you'd prefer to use the session storage configuration from your exissting PHP environment. With the following configuration you disable Roundcube's custom session save handlers and fall back to PHP's default session handling:
$config['session_storage'] = 'php';
Sharing attachment upload files
The last part that needs to be addressed in a multi-server setup is the storage of files uploaded for being attached to outgoing messages. These by default are saved in a temporary folder on the local file system. When using round-robin load balancing that obviously doesn't work reliably and leads to missing attachments files when the "message send" operation hits another Roundcube instance than the upload did. Thus attachment files need to be stored in a place where all the Roundcube instances have read and write access to. This could be a
- Network storage device
- Database table
- Custom solution
Saving temp files on a network share
The simplest way to have shared access to attachment files is to mount a network share (e.g. via NFS) and configure Roundcube to use that instead of the local temp folder:
// use this folder to store temp files (must be writeable for apache user) $config['temp_dir'] = '/mnt/some-network-mounted-volume/';
Storing attachments in database
Uploaded files can also be stored in Roundcube's database which already is accessible for all instances. Therefore Roundcube by default ships a plugin named
database_attachments which just needs to be enabled and configured. Read how to enable plugins in our wiki. That plugin itself has some more configuration options that'll let you store attachments in memcache instead of the database.
To take this one step further, another plugin named redundant_attachments can be chosen over the 'database_attachments' plugin. This one provides a more fail-safe solution by storing attachments in both, the database and the local file system with an additional fall-back to memcache in case the database write-master is unavailable.
Implement a custom storage plugin
Temporary attachment file storage is entirely handled by plugins in Roundcube. Even the default storage in the local file system is done by a plugin. This makes it very easy to add a custom storage method for these file. Read How to Write a Plugin and have a look at the existing implementations in either one of the default plugins: filesystem_attachments, database_attachments or redundant_attachments.
The only requirement for integrating your custom attachment handler plugin is to extend the
filesystem_attachments plugin class. Then just override the methods defined in that plugin class.