Introduction

So you've read up on what RoundCube is, and what it can do. But of course, you can't really know if you like it or not, unless you install it and use it for yourself for a week or two. This document will help guide you through a standard installation of Roundcube. NOTE: The code-base for this is the 0.1-beta release.

Install RoundCube with IIS and hMailServer

There's a nice ​how-to about the installation of RoundCube on a Windows box with IIS6 and hMailServer. NOTE: Make sure you set temp_dir in main.inc.php to an absolute path as otherwise users may run into issues with attaching files to emails.

Installation

Get Roundcube!!

Well obviously we need to get Roundcube before we can use it. The easiest way to get it is to visit ​http://www.roundcube.net and click on "Downloads" or just go to http://www.roundcube.net/?p=downloads. Wait for it to download, and then unzip (using WinZip? (or ZipGenius?) or "tar xvfz roundcubemail-0.1beta.tar.gz") in the current directory.

Get it ready

Now that we've got our files, we need to edit two of them. That's right, only two files are edited to get Roundcube working!! The two files are in the "/config/" directory of Roundcube. Open up the following in your favorite editor: "main.inc.php.dist" and "db.inc.php.dist".

Database Configuration

First thing we need to do is decide what database backend we'll use. The most common is mySQL but others are PostgreSQL and SQLite. So once you decide, think about the username and password you want to use, as well as a name for a database to use. Once you've decided that, write it out like this:

backend:username:password@domain.com/database

An example would be "mysql://demouser:password@mydomain.com/roundcube". Now, take that and in the "db.inc.php.dist" file find the line that starts with: $rcmail_config['db_dsnw'] and replace the string that is currently there with the one we've come up with. Save that file as "db.inc.php" (note that we dropped the "dist" off the name).

If you are using MySQL, be sure to flush the users privileges when you add a new user or you will get a database connection error: FLUSH PRIVILEGES;

Mail Server Setup

Now in "main.inc.php" and we've got quite a few options. The first thing we should do is set the caching level to false. This is only advisable when the mail server is on your server; however, some issues have arisen with caching enabled. So for now, we'll disable it and you can enable it later if you feel. So find this line:

$rcmail_config['enable_caching'] = TRUE;

and replace "TRUE" with "FALSE". Next thing we need to do is set up the mail server. Skip down a few lines to the one that is this:

$rcmail_config['default_host'] = '';

There are two options here: multiple hosts or single hosts. Multiple hosts will be within an array. We'll go over a single mail server setup here.

Replace the inside the "" you need to put your mail server. Normally this would be "imap.domain.com" or "mail.domain.com". Either one will work, as long as the server is an IMAP server, not a POP3 server. An example would be:

$rcmail_config['default_host'] = 'imap.domain.com';

For an SSL connection, just use "ssl://imap.domain.com". The next setting is the port to use. IMAP defaults to port 143. Set this to your port number. If it's SSL, the default is 993.

$rcmail_config['default_port'] = 143;

Now skip on down to the smtp server information. You should see this setting:

$rcmail_config['smtp_server'] = '';

With that you need to put the SMTP server inside the "" so a simple example would be:

$rcmail_config['smtp_server'] = 'smtp.domain.com';

Once again, if it's over SSL use "ssl://smtp.domain.com". Again change the port in the next setting. Default is 25, and SSL default is 465.

$rcmail_config['smtp_port'] = 25;

The next two settings (SMTP User and SMTP Password) need to be set (if you want to send from Roundcube). They are simple, so it's better to just give them to you:

$rcmail_config['smtp_user'] = '%u'; $rcmail_config['smtp_pass'] = '%p';

Save this file now as "main.inc.php" (note that the "dist" has been dropped).

Upload Files

Okay, so now we've got everything ready, we can upload our files!! So use your favorite FTP program and upload everything to your website.

Files permission

Make sure that the following directories (and the files within) are writable by the webserver :

• /temp
• /logs

Protect your installation

Access through your webserver to the following directories should be denied :

• /conf
• /temp
• /logs

The following Apache access rules will do the job (adapt to your installation) :

<Directory /path/to/roundcube/config/>
    Order allow,deny
    Deny from all
</Directory>

<Directory /path/to/roundcube/logs/>
    Order allow,deny
    Deny from all
</Directory>

<Directory /path/to/roundcube/temp/>
    Order allow,deny
    Deny from all
</Directory>

Database Setup

While we're uploading (or after we're done) we have one final step to do before we can start using Roundcube. We need to set up our database. Open your website control panel. You first need to create a database and user with the information we decided earlier. Then add that user to the database. Next we execute the SQL file found in the "/SQL/" directory in Roundcube that is named: "*.initial.sql" where * is your database backend type (mySQL, PostgreSQL, SQLite).

For example with mysql enter the following code on the command line:

mysql --user=(your_db_user_name) -p (your_db_name) < mysql.initial.sql

Conclusion

This is a very basic setup to get you up and running with Roundcube in less than twenty minutes. There are plenty of other options, and a lot more options to investigate. See Howto_Config or browse the forums (​http://www.roundcubeforum.net) for other tricks and modifications, as well as support if you just can't get it working.

Have fun with your new Roundcube installation!!

Troubleshooting

500 Internal Server Error::

This is a very common problem. One solution is to either empty out the .htaccess file, or delete it entirely, in the root of the RoundCube installation folder.

Using MySQL - Database Error | Failed Connection

Make sure your database connection string is correct. If you are using MySQL 4.1 or above, your client libraries may not support the new password encryption protocol: ​http://dev.mysql.com/doc/refman/5.0/en/old-client.html

Other Issues::

If you're still having trouble after a following the steps above, feel free to drop by the ​RoundCube Forum for some assistance.