tenny.org

HOW TO: RoundCube Webmail Setup on Your Server

RoundCube

I have been keeping my eye out for a new web mail client for some time. Horde just hasn’t been cutting it for me. I had heard through a few sites how great RoundCube was so I did some additional research. I thought this would be a good way for me to “keep my skills fresh” and actually allow me to functionally improve my email experience. Per the RoundCube website (roundcube.net) the program itself is defined as a “browser-based multilingual IMAP client with an application-like user interface”. Admittedly RoundCube is only in the alpha stage of development, which shows during the installation and in some of its limited capabilities (no calendar, attachment system is a little rough still, etc.). Now for those skeptics out there who think there is better software out there; I did look at a few competitors such as AtMail (looks amazing, but not open source), Zimbra (again looks good, but bloated at over 150 MB) and a few others. If you want my three key points to why you should consider RoundCube, here they are:

Open Sourced
Small install
AJAX interface is fantastic!

Still not sure it is right for you?

Go use the RoundCube Demo, it is slow but that is because it is the demo. If you have 20 minutes just it up on your server and it’ll be much faster I promise.

Before we begin the installation there are some things you are going to need.
- PHP and MySQL support on your server
- An FTP client (Get Filezilla if you need a client) or some other way of uploading files to your server
- A achieve opener (I use WinRar)
- A terminal or command line application if you want use the CVS build of RoundCube (totally not covered here, but a great online tutorial is available at Paul Stamatiou’s site

Installation

Let’s get started by creating the MySQL database on your web hosting environment. I use CPanel as a front end so the following instructions apply more for CPanel. CPanel users on a shared server environment need to log into www.domain.com/cpanel and click on MySQL Databases on the right panel. Once here, scroll to the bottom and enter the database name in the DB field and then click the Add DB button. For this tutorial I named my database RoundCube. Now that you have a database you will need to create a user, scroll to the bottom again and enter a username and password (for this tutorial I named my username:roundcube and password:xxxxxx) in the user section and click the Add User button. Now that you have both a database and user you need to link them, to do so select your RoundCube user from the user drop down and then select your RoundCube database from the Db drop down. In the privileges section make sure that only the All box is checked and then click the Add user to DB button. When finished your database information should look like this:

RoundCube

Users in roundcube
roundcube (Privileges: ALL PRIVILEGES)

Connection Strings
Perl $dbh = DBI->connect(“DBI:mysql:roundcube:localhost”,”roundcube”,” “);
PHP $dbh=mysql_connect (“localhost”, “roundcube”, “ “) or die (‘I cannot connect to the database because: ‘ . mysql_error());
mysql_select_db (“roundcube”);

Now that your database is built you can start with the roundcube software. Start by going to RoundCube and downloading the latest release. When the download has finished unpack it to a directory on your computer so we can begin configuring it.

Open up the roundcubemail folder on your computer and then go to the config folder. Here you should have both db.inc.php and main.inc.php. These are the main files we will use for configuring the service.

Time to Config Files

Let’s start by editing db.inc.php in a text editor. The only thing required to begin using the service is enabling database access. Find the line that says

$rcmail_config['db_dsnw']=’mysql:// roundcube:pass@localhost/roundcubemail’;

Replace where it says roundcube with your database login and pass with the database password. Localhost is a default setting and should remain the same on most configurations. The last thing to change is roundcubemail by replacing it with your database’s full name. Using the examples I used earlier in creating the MySQL database my config line now looks like this:

$rcmail_config['db_dsnw']=’mysql:// roundcube:xxxxxx@localhost/roundcube’;

That’s all we need to edit in this file, so now we can save and close it.

Next we need to open main.inc.php in a text editor. There are many things you can do here to improve the user experience of your web mail. By default roundcube shows you a username, password, and server. However, you can add one or multiple values to default_host so you don’t have to type it in every time you log in. Another edit changes the session time (which is 10 minutes by default) to 30 minutes. And then the last thing I’ll focus on is editing your time zone. I put -6 as I currently reside in the Midwest (central time), so it depends where you live.

***for only 1 host use this setting***
// the mail host chosen to perform the log-in
// leave blank to show a textbox at login, give a list of hosts
// to display a pulldown menu or set one host as string.
// To use SSL connection, enter ssl://hostname:993
$rcmail_config['default_host'] = ‘mail.domain.com’;

***for using with multiple domains use this setting***
// the mail host chosen to perform the log-in

// leave blank to show a textbox at login, give a list of hosts
// to display a pulldown menu or set one host as string.
// To use SSL connection, enter ssl://hostname:993
$rcmail_config['default_host'] = array(‘mail.domain.com’, ‘mail.domain2.com’,’mail.domain3.com’);

// session lifetime in minutes
$rcmail_config['session_lifetime'] = 30;

// use this timezone to display date/time
$rcmail_config['timezone'] = -6;

Save the file and exit your text editor. Now that we are done it is time to upload the software to your web server. One of the things I did to make using the service easier is to create a sub-domain in CPanel called webmail.domain.com. When I uploaded the software I dumped it directly into the webmail folder.

Now after you have completed the upload you’ll need to chande your attributes for your temp and log files in your RoundCube folder. If you have Filezilla you can do this using these steps:
1. Right click on the directory and then select file attributes.
2. In the file attributes screen put a check in all of the boxes or just type 777 in the numeric value box and then click ok.

There is only one more thing you need to do to get started with RoundCube. You need to create the tables required by RoundCube in your MySQL database. Go back to your MySQL Databases screen in CPanel and scroll to the very bottom. Click on the PhpMyAdmin link. PhpMyAdmin is the preferred MySQL database management tool in the industry. Once it is open there is a dropdown menu on the left screen; click on it and select your RoundCube database. When the database opens on the right go to the SQL tab. There is an empty box labeled Run SQL query/queries on database. Next to this box click the browse button and find the mysql.initial.sql file located in the roundcube folder within the SQL folder. Once found click Open and the click the Go button. This will import several tables into your mySQL database if it worked correctly for you.

You are now ready to try it!

You should now be able to access your RoundCube installation by going to the directory where you placed your RoundCube folder (http://webmail.domain.com). Once the page has loaded, go ahead and try to login. If you do not know what your login is go back into your CPanel and choose the Mail button. Once in Mail click Manage/Add/Remove Accounts. This will bring you to a screen listing all of the addresses on your account. If you need a new address this is where you will need to add it (not within RoundCube). Next to the address you want to use in RoundCube click the Configuring Mail Client button. Here it will list out your mail server settings.

RoundCube Login Page

RoundCube Troubleshooting

There are a few potential issues you may encounter in the install that are fixed pretty easily. The most common error is a 500 Internal Server Error. This is caused by the .htaccess file in your RoundCube config folder. To correct this, ftp into your web mail server and delete the .htaccess file from the config folder. After deleting the file refresh your web mail page and you should be all set.

Another potential error is a Parse error, unexpected T_STRING in either db.inc.php or main.inc.php. This is caused by an incorrect string in your config files. My recommendation is to start over with these 2 files and try again. If you want to try and fix the errors my recommendation is to recheck all of your code thoroughly. CSS Modifications

Customizing your RoundCube

There are many ways you can customize your roundcube web mail. These are very well documented on Paul Stamatiou site so I recommend checking it out!