Roundcube featured image

Installing Webmail Client with Roundcube on Ubuntu 20.04: A Tutorial

Roundcube is an open-source IMAP browser-based email client. It has gained popularity for supporting ACLs and utilizing AJAX (Asynchronous JavaScript and XML) technology. It has excellent features and end-to-end functionalities like email management, MIME support, and folder manipulation, to name a few. Besides, Roundcube offers message searching, spelling checks, calendars, and contact management seamlessly. Above all, it has a robust plugin repository and added customization options compared to other popular browser-based clients.

Roundcube is a MUA. Unlike MTA, you will need a service that manages your email, preferably using your mail server. Check out our Mail Server Configuration tutorial to add the mail server of your choice.

When you send an email, the MUA transfers it to its MTA server using SMTP. After a few jumps, the receiving MTA gets the email and transfers it to their MDA using IMAP. At last, the receiver views the email using MUA.

Let’s understand these terms:

  • MUA: A mail user agent is an interface that enables a user interaction to view and send emails.
  • MTA: A mail transfer agent transfers email from the sender to the receiver.
  • SMTP: A Simple Mail Transfer Protocol is a protocol that the MUA uses to send emails to the MTA.
  • MDA: All emails sent from the MTA get received and stored at the mail delivery agent.
  • IMAP: Internet Message Access Protocol is a protocol that MDAs use to deliver mail to the MUA.

In this tutorial, we’ll walk you through the steps of installing a webmail client with Roundcube on Ubuntu 20.04.

Let’s Start!

Prerequisites

To follow along with this tutorial, you’ll need the following:

Step 1: Install Extensions and Dependencies

Before we start, let’s update the repositories to avoid software clashes:

Next, we’ll install the Roundcube dependencies and configure PHP. Use the following command to install PHP extensions and libraries:

By default, a few of the PHP libraries are disabled. We need to enable those libraries by navigating the server’s php.ini file located at /etc/php/7.0/apache2/php.ini. Open the php.ini file using nano text editor:

Unlike most commonly used commenting options starting with a hashtag ( #), we use a semicolon ( ;) to comment and uncomment lines. Add a leading semicolon to comment on a line. Likewise, remove a semicolon to uncomment a line.

Let’s look at the section containing commented lines starting with extension=. Remove the semicolons to uncomment php_mbstring.dll and php_xmlrpc.dll extensions:

Additionally, append the extension=dom.so at the bottom of the extension block:

  • Modify Files:
    • Change the date.timezone:

Go to the settings option, navigate to date.timezone, and uncomment it. Next, add your timezone using quotations. Check out PHP’s timezone page to see how the formatted timezone looks in the php.ini file. For instance, if you are from Europe, your file will look like this:

    • Modify the upload_max_filesize file:

Then, navigate to the upload_max_filesize setting. By default, you will see the maximum limit set as 2MB. Based on your needs, you can increase the maximum file size to any extent. However, most email servers limit the total attachment size up to 10MB. In this guide, we’ll keep the maximum size is 13MB so that multiple users add attachments at the same time:

    • Modify the post_max_size file:

Now, navigate to the search for post_max_size. Unlike the upload_max_filesize setting that applies to attachments, post_max_size gets applied to the size of the whole email (including attachments). Let’s set our post_max_size at a higher value to prevent deadlocks:

    • Set the func_overload value:

Finally, look for mbstring.func_overload = 0 and uncomment it. Also, ensure that its value is set to null so that it supports multibyte string functions:

Save all the modifications and then close the file. Our server is set up with the LAMP stack, Roundcube’s dependencies, and the required PHP configuration. In the next step, we are going to download the Roundcube software, install it, and configure it.

Step 2: Download Roundcube

Go to the Roundcube download page, choose the Stable version section and browse at the Complete package. Then, right-click on the Download button and select Copy Link Address. Using the address with wget, download the Roundcube tarball on the server:

After that, you will need to decompress the Roundcube archive:

The arguments used may sound confusing, especially if you are completely new. Here is an explanation of what each flag means:

  • x: Stands for extract.
  • v: Stands for verbose.
    • Informs tar to print the path and names of the extracted files.
  • z: Informs tar to remove the tar wrapper and decompress the archive using gzip.
    • The compressed gzip file extension will have .gz in the end.
  • f: Stands for file.

Omit the trailing / in the directory because we are moving and renaming the entire directory, and not just the contents in it. Now, let’s move the decompressed directory to /var/www and rename it as roundcube:

Set permissions for Apache to create and edit the configuration and the logs files. Then, change the owner and group to www-data. Also, make sure to allow the read and write permissions for the owner and group:

Though we have downloaded Roundcube’s code and set the necessary permissions, our installation is still incomplete. Connecting Roundcube to our database via Roundcube’s GUI is yet to be done. Before we proceed further, we need to update Apache and its configuration to inform the base location of Roundcube.

Step 3: Apache Setup and Configuration

In this step, we’ll edit the virtual host file to configure Apache. Using Apache virtual hosting, we will host multiple sites on a single server. Even though Apache is hosting a single site, it’s less messy and simple to use a virtual host configuration file compared to editing Apache configuration. To add an extra layer of safety, consider securing Apache with Let’s Encrypt.

Each .conf file in the /etc/apache2/sites-available/ represents a different site. Let’s create a virtual host file here for Roundcube and inform Apache to make it available for the browser.

First, copy the default configuration file to use it as a starting point for the new file:

Open the file using nano text editor:

There are several changes we will need to modify. Let’s walk through each, and then provide the entire file to copy and paste.

First, change the following directives in the existing VirtualBlock host:

  • ServerName: Informs Apache to pick the domain.
    • If you are using one server, then this ServerName will be your server IP address or domain name.
  • DocumentRoot: When the traffic comes in, it routes where to send it.
    • In our tutorial, we will be sending traffic to Roundcube at /var/www/roundcube.
  • ServerAdmin: If there arises an issue with Apache, the ServerAdmin specifies a contact email address.
  • ErrorLog and CustomLog: Defines where to save successful connection logs and error logs for this site.
    • Use specific names to define error logs so that if there are any issues specific to the site, it gets detected effortlessly.

Then, you’ll add a new Directory block that informs Apache what to do with the Roundcube directory. The Directory consists of two words, where the first word in each line is the configuration name followed by the actual configuration options.

  • Options -Indexes: Informs Apache to display a warning if it finds an index.html or index.php file missing. By default, it displays the contents of the directory.
  • AllowOverride All: Informs Apache that if a local .htaccess file is detected, it must override the global settings.
  • Order allow,deny: Instructs Apache to match the client’s access to the site and deny the unmatched ones.
  • allow from all: Defines the type of allowed clients.

Once you’ve made these changes, you will see the file like:

Save all the changes and close the file. Now, let’s request Apache to stop hosting the default site:

After that, we’ll instruct Apache to start hosting the Roundcube site instead. When enabling the site, don’t include the .conf  because the a2ensite requires the filename with no extension:

Next, turn ON the mod_rewrite Apache module:

Finally, restart Apache to enable Roundcube installation accessibility:

In the last step, we need to configure the database, so Roundcube can store and manage its app-specific data.

Step 4: MySQL Setup and Configuration

Try accessing your server using the IP address or domain name. You’ll see a configuration error appearing on the page. Here, Roundcube checks for a file generated during the configuration setup, but our configuration setup is incomplete. Before we set up our configuration, let’s make our database ready.

  1. Connect to MySQL: Let’s connect to the MySQL interactive shell using the username and password:
    Once you hit the above command, you’ll be asked to authenticate yourself with the root password that you have created while installing MySQL.
  2. Create Database and User: Now that you are successfully logged in, let’s create a database and a database user. After that, we’ll allow user permissions to execute commands on our new database.
  3. Create the Database: Use the following command to create a database called roundcubemail. Next, provide database options like the character set to use utf8:
    MySQL offers robust security and advanced safety. It defines a user by name and the source of connection. The above command creates a user called roundcube and defines the user to connect from localhost.
  4. Rename the Database: Let’s rename the user and modify our password:
  5. Set Permissions: Allow roundcube users all permissions on the roundcubemail database and tables:
    Save your changes and exit from the MySQL interactive shell:

Our next step is to set up the database structure that helps Roundcube save all information. Roundcube comes with a database file that sets up the data automatically, which would require strenuous efforts to configure manually.

Using the following command, MySQL will use our newly created user to read in a file /var/www/roundcube/SQL/mysql.initial.sql. Also, it will apply the configuration to the database roundcubemail:

Now, you will be asked to enter the roundcube user’s password. Our database setup prepares Roundcube’s use and allows us to verify the right permissions. If all the steps were successfully done, there’ll be no feedback and then you will come back at your command prompt. In the next step, we’ll tell Roundcube our email settings and complete the installation.

Step 5: Roundcube Setup and Configurations

If you try accessing your Roundcube installation now, you’ll get an error page. Visit http://your_server_ip_or_domain/installer to complete the installation.

If the set-up is done properly, you’ll see a green OK to the right of every line item. However, you may not see the green OK in optional LDAP settings in MySQL. If you see the message NOT AVAILABLE next to any other line, you have to install these unavailable dependencies. If you missed out on downloading any of the dependencies, you can navigate the URL and download it right away.

Once the set-up is done, scroll down and click the NEXT button. Let’s walk through generating the Roundcube configuration file. Check out the portions of the form we need to modify.

  • General Configuration

There are a few customizations and some general settings that we will modify in the General configuration section:

  • ip_check: It is a security configuration option and verifies the client’s IP in session authorization.
  • product_name: Rename the product name as you like. This name maps “Roundcube” in text and gets replaced with this name instead.
  • support_url: Support in the Roundcube installation. If you don’t have a dedicated help desk site, prefer using an email address like walker:paul@demo.com.
  • skin_logo: Replace the Roundcube logo with skin_logo. To enable HTTPS, choose an HTTPS URL image (178px by 47px).

Leave the other settings with their default values.

  1. Logging & Debugging: Let’s go with the default options.
  2. Setting up the Database: Instead of using your mail explicitly, Roundcube uses MySQL to store the information for running the web client. Here, we need to inform Roundcube to access the database we have set up in Step 4. Use the database credentials we have created previously:
    • Database: MySQL
    • Server: localhost
    • Name of database: roundcubemail
    • User: roundcube
    • Password: demo12345@
      • Use the password you defined we have set up in Step 4.
    • Db_prefix: This is optional unless you are using a shared database with other apps.
  3. Modifying IMAP: Let’s set the IMAP and SMTP settings for your email server. As this tutorial focuses on using Gmail as an example, we’ll be using the Gmail settings in our IMAP settings. However, if you choose to opt for other service providers like Yahoo or Outlook, you need to use their respective settings. Many email providers support connections with or without encryption. Normalize using the SSL IMAP/SMTP URLs and ports to avoid using non-secure connections.
    • default_host: ssl://imap.gmail.com
    • default_port: 993
    • auto_create_user: Yes ☑
      • If this is unchecked, Roundcube will not create a user in its own database and prevent you from logging in.
    • *_mbox fields: Keep the default values.
      • You can update this later in the Roundcube UI.
  4. Modifying SMTP: The SMTP server is an integral part of the email that is used to send emails. Similar to the IMAP server section, we’ll use the SSL URL and port. If you are inexperienced in using SMTP servers, follow SMTP best practices to learn more about these kinds of servers. Here we are using Gmail as our example:
    • smtp_server field: ssl://smtp.gmail.com
    • smtp_port field: 465
    • SMTP and IMAP are two different services, therefore they both need a username and password. However, Roundcube allows us to use the IMAP credentials, so there is no need to recreate them. Leave the fields under smtp_user/smtp_pass blank and check the box next to Use the current IMAP username and password for SMTP authentication.
    • smtp_log: Yes ☑
  5. Modifying Display Settings & User Prefs: Let’s go with the default display settings and user prefs. If you choose to customize your Roundcube installation, click the RFC1766 link on the configuration page and update the language field manually.
  6. Plugins: Roundcube offers plugin support that adds extra security. Plugins are optional, however, you can leverage them to make your work easier. Let’s have a look at the list of the most used plugins:
    • archive: This plugin provides an Archive button which is similar to how Gmail works.
    • emoticons: This allows the use of emoticons in emails.
    • enigma: It makes it easy to use GPG email encryption.
    • filesystem_attachments: It allows to save attachments to the Roundcube server temporarily when saving a draft email.
    • hide_blockquote: This plugin hides the quoted portion of replied emails to keep the UI clean.
    • identity_select: It allows the user to select multiple email addresses while composing an email.
    • markasjunk: This plugin allows to mark an email as spam and move it to the Spam folder.
    • newmail_notifier: Alerts you to new emails using the browser notification system.

Hit the UPDATE CONFIG button to save your settings. In the last step, we’ll test the Roundcube configuration to ensure that everything is working fine.

Step 6: Test the Roundcube Set Up

Once you update the configuration, the page will refresh and a yellow info box will appear at the top of the page saying that The config file was saved successfully into the RCMAIL_CONFIG_DIR directory of your Roundcube installation.

Then, click on the CONTINUE button to test your configuration. Similarly to the dependency check page, you’ll see a green OK marker on every line provided there are no errors. If you see any errors, go back and double-check your inputs.

Put in your IMAP and SMTP username and password in the Test SMTP config and Test IMAP config sections respectively to test the rest of the configuration. Similarly, click on Send test email and Check login. If you have followed all the steps correctly, the page will refresh and you’ll see the green OK under the tested section.

Note: If you are using Gmail with two-step authentication enabled, consider generating an app-specific password because Roundcube is not aware of how to prompt for your two-step auth token. Follow the same password generation procedure while using other email server alternatives like Yahoo or Outlook.

Once you’ve verified that both SMTP and IMAP connections are running fine, the next step is to remove the installer directory using SSH. Removing the installer directory is a secure way to prevent others from generating a new config and overriding the correct settings:

Finally, you can go to the Roundcube instance using your server’s IP and verify your email.

Conclusion

In this tutorial, we have learned to install a webmail client using Roundcube on Ubuntu 20.04. In addition to the steps discussed above, there are other security options like HTTPS support and GPG encryption that you must consider adding. Take it as a responsibility to protect your servers using robust security measures.

Furthermore, there are many other learning materials on Redis and PHP that you can access from our blogs:

Happy Computing!