Handle Gmail with Roundcube Webmail User Agent

In this tutorial we will describe how to install and configure the latest version of the Roundcube Webmail User Agent in Debian to manage emails from one of the most popular email services, Google Gmail. We will use the Roundcube webmail client as an interface to the secured IMAP and SMTP services of a Gmail account and manage all emails locally on our own web server.

Roundcube is a free open-source webmail user agent or web client written in PHP and Ajax, mostly deployed on Linux with Apache/Nginx, PHP and MySQL/MariaDB components, that only requires access to an IMAP/S and/or an SMTP/S server to synchronize mail files and/or send messages. Major universities and companies around the world, as well as one of the most popular web hosting panels, Cpanel WHM, use the Roundcube webmail client to manage emails.


  • Install Debian 9.1 on a bare-metal machine or on a virtual private server
  • A static IP address configured for one of your system’s network cards
  • sudo root privileges for a local or remote account or direct access to the root account
  • A private or public domain name with the correct DNS records

First configurations

Before you install the Roundcube webmail client from the sources on your own server, you need to make sure that your system meets all the software requirements for compiling and installing the application. In the first step, update your system repositories and software packages by running the following command.

apt update
apt upgrade

In the next step, run the following command to install some necessary utilities to further manage your system from the command line.

apt install wget bash-completion

Next, set the name for your system by running the following command. Replace the FQDN of your server accordingly.

hostnamectl set-hostname server

Check the hostname of the machine and the hosts file by running the following commands.

cat /etc/hostname
hostname –s
hostname -f

Finally, restart the Debian server so that the kernel updates and hostname changes can be properly applied.

systemctl reboot

Roundcube is a web-based client mail application written primarily in the PHP server-side programming language and Ajax. In order to run Roundcube’s PHP file scripts, a web server such as Apache HTTP Server and a PHP interpreter need to be installed and made operational in the system. To install the Apache web server and PHP interpreter along with all the required PHP modules that Roundcube needs to run properly, enter the following command in your server console.

apt install apache2 libapache2-mod-php7.0 php7.0 php7.0-xml php7.0-gd php7.0-json php7.0-zip php7.0-intl php7.0-mbstring php-imagick php7.0-imap php-pear

After installing Apache and PHP, test that the web server is running and listening for network connections on port 80 by entering the following command with root privileges.

netstat –tlpn

If the netstat network utility is not installed by default in your Debian system, run the following command to install it.

apt install net-tools

From the netstat command output, you can see that the Apache web server is listening for incoming network connections on port 80.

If you have a firewall enabled on your system, such as the UFW firewall application, you should add a new rule to allow HTTP traffic through the firewall by running the following command.

ufw allow WWW


ufw allow 80/tcp

Next, enable the following Apache modules that the Roundcube webmail client needs to work properly by entering the following command.

a2enmod rewrite headers expires deflate
systemctl restart apache2

Finally, test if the default web page of the Apache web server can be displayed in your clients’ browsers by calling the IP address of your Debian machine via the HTTP protocol (see figure below). If you do not know the IP address of your machine, you can run the ifconfig or ip a commands to find out the IP address of your server.


In the next step, we need to make more changes to the PHP default configuration file to ensure that the following PHP variables are enabled and the PHP time zone setting is configured correctly and matches the geographical location of your system. Open the /etc/php/7.0/apache2/php.ini file for editing and make sure the following lines are set as shown. First, make a backup copy of the PHP configuration file.

cp /etc/php/7.0/apache2/php.ini{,.backup}
nano /etc/php/7.0/apache2/php.ini

Find , edit and change the following variables in the php.ini configuration file:

file_uploads = On
error_reporting E_ALL & ~E_NOTICE & ~E_STRICT
memory_limit = 128 MB 
session.auto_start = 0
mbstring.func_overload = 0
date.timezone = Europe/London

Increase the variable memory_limit to support large attachments, and replace the variable time.zone variable according to your physical time by consulting the list of timezones in the PHP documents at the following link: http: //php.net/manual/en/timezones.php

After you have made all the changes described above, restart the Apache daemon with the following command to apply the new changes.

systemctl restart apache2

Finally, create a PHP info file by running the following command, and verify that the PHP timezone is configured correctly by accessing the PHP info file in a browser at the following URL, as shown in the figure below. Scroll down to the date setting to verify the PHP time zone configuration.

echo '<?php phpinfo(); ?>'| tee /var/www/html/info.php


TheRoundcube webmail app stores various configurations such as users, sessions, contacts, and others in an RDBMS database. In this tutorial, we will configure Roundcube using the MariaDB database backend. Enter the following command to install the MariaDB database and the PHP module needed to access the mysql database.

apt install mariadb-server php7.0-mysql

After you install MariaDB, use the netstat command to check if the daemon is running and waiting for connections on localhost, port 3306.

netstat –tlpn | grep mysql

Then log in to the MySQL console and secure the MariaDB root account by running the following commands.

mysql -h localhost
use mysql;
update user set plugin='' where user='root';
flush privileges;

In the next step, secure MariaDB by running the mysql_secure_installation script included in the installation packages from the Debian Stretch repositories. As the script runs, it asks a series of questions about securing the MariaDB database, such as changing the MySQL root password, removing anonymous users, disabling removed root logins, and deleting the test database. Run the script with the following command and make sure you answer yes to all questions to fully secure the MySQL daemon. Use the excerpt from the script below as a guide.

sudo mysql_secure_installation

To test the security of MariaDB, try logging into the database from the console without a root password. Access to the database should be denied if no password is provided for the root account. If the password is provided, you should be able to log in to the MySQL console, as shown in the screenshot below.

mysql -h localhost -u root
mysql -h localhost -u root –p

Next, log in to the MariaDB database console and create a database to use for Roundcube and a user with a password to use for managing the Roundcube database by entering the following commands. Replace the database name, user and password accordingly.

mysql –u root -p
CREATE DATABASE roundcube_db CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON roundcube_db.* TO 'user_roundcube'@'localhost' IDENTIFIED BY 'roundcube_pass';

To apply all the changes made so far, restart the MySQL and Apache daemons and verify that the daemons are running by entering the following commands.

systemctl restart mysql apache2
systemctl status mysql apache2

Install and configure Roundcube

If all system requirements for installing Roundcube are met, visit the official Roundcube website https://roundcube.net/download/ and download the latest version of the compressed Roundcube tarball archive using the wget utility, as shown in the following example.

wget https://github.com/roundcube/roundcubemail/releases/download/1.3.1/roundcubemail-1.3.1-complete.tar.gz

After the tarball download is complete, unzip the gzip-compressed Roundcube archive and copy the installation files to the root directory of your web server by executing the following commands. Also, remove the index.html file installed by default by the Apache web server from the webroot. Note that the cp command in recursive mode does not copy the dot or hidden files. You have to copy the hidden files manually .htaccess file from the unzipped archive to the Apache webroot.

tar xfz roundcubemail-1.3.1-complete.tar.gz
rm /var/www/html/index.html
cp -rf roundcubemail-1.3.1/* /var/www/html/
ls /var/www/html/
cp roundcubemail-1.3.1/.htaccess /var/www/html

Next, run the following commands to grant the Apache runtime user full write permissions to the following roundcube directories in the webroot path. However, first change the path to your Apache webroot path to grant permissions to the directories in the oneshot.

cd /var/www/html/
chown -R www-data:www-data temp/ logs/ config/
ls –al
cd  #Go back to home

Since Debian 9 ships with PHP version 7 by default, you need to change the PHP version in .htaccess file from mod_php5.c to mod_php7.c by running the following command. Use the head command to check the .htaccess file before and after applying the changes with the sed command.

head /var/www/html/.htaccess
sed -i.bak 's/mod_php5.c/mod_php7.c/g' /var/www/html/.htaccess
head /var/www/html/.htaccess

Before you start installing Roundcube Webmail via the web interface, run the following command to populate the MySQL database created for the Roundcube installation with the correct tables.

mysql -u user_roundcube roundcube_db -p < /var/www/html/SQL/mysql.initial.sql

To verify that the Roundcube database has been populated with all the required information, enter the following command. The result should match the output on the screenshot below.

mysql -u user_roundcube roundcube_db -p -e 'show tables'

Proceed with the Roundcube webmail installation by opening a browser and navigating to the IP address or domain name of your server via the HTTP protocol. On the first installation screen, the Roundcube Webmail Installer PHP script performs a series of environment tests and checks if the required PHP extensions from the presented list are installed in the system, if any of the required RDBMS databases are installed, if the required third-party libraries are installed in the system and if the php.ini and .htaccess file are configured with the correct settings recommended for the Roundcube installation. All the described checks are shown in the following images.

In the next section of the installation screen, General Configuration, the web-driven installer creates the Roundcube configuration file with the parameters you specify in the web forms. First, add a new name for this Roundcube product name and also change other variables, such as a new logo for Roundcube. Leave temp_dir, des_key and other variables as default and scroll down to get to the next section of configuration.

In the next section of the Roundcube Webmail installer, Logging & Debugging, check the Log errors on debug_level option and select to write the messages to a file. Leave the log_dir, syslog_id and syslog_facility options as default and scroll down to get to the next section of the installation.

In the next section of the Roundcube Webmail Installer, add the MySQL database name and credentials you created earlier for Roundcube and scroll down to get to the next section of the Roundcube installation.

In the next section, we specify the IMAP settings that Roundcube needs to synchronize with Gmail’s IMAP server, as follows.

  • Add the following address for the Gmail IMAP server to the default_host parameter: ssl://imap.gmail.com
  • To the default_port parameter add the Gmail IMAP port 993
  • On the parameter username_domain write com domain
  • Enable the auto_create_user parameter so that Roundcube automatically creates a new user when you log in for the first time

Leave the parameters for sent_mbox, trash_mbox, drafts_mbox and junk_mbox as default and scroll down to get to the next installation section.

In the SMTP Settings section of the Roundcube Webmail installation, add the following values to configure the Gmail SMTP server: For smtp_server, add the address ssl://smtp.gmail.com and for smtp_port , add the port number 465. Leave the smtp_user/smtp_pass parameters empty and enable the“Use the current IMAP username and password for SMTP authentication” and“Log sent messages to {log_dir/sendmail} or to syslog” options, as shown in the figure below. When you’re done, scroll down to get to the next installation section.

In the Display Settings & User Preferences section, you have two options to select the language for Roundcube, which may be different from your default locale settings, the theme (skin) used by Roundcube, the number of items to display in the message and contact list views, and whether you want to display and compose new email messages in HTML Hyper Text Markup Language. You can change the settings in this section according to your needs or leave the other options as default, as shown in the figure below. When you are done, scroll down to get to the last section of the Roundcube installer.

In the last section of the Roundcube webmail installer, select the plugins you want to install and activate in Roundcube from the list, as shown in the screenshots below. Once you have selected the plugins you want to install, scroll to the bottom of the screen and click the Create Config button to create the Roundcube configuration file. In this case, the configuration file for Roundcube is located in the file /var/www/html/config/config.inc.php.

After the configuration file is successfully created, the next screen will display a message in your browser informing you of this fact. Click the Next button here to proceed to the next installation screen, as shown in the figure below.

In the last screen, the Roundcube Webmail Installer script performs some final checks on the configuration file, checks if the roundcube temp and logs directories are writable by the server runtime user, and also checks the MySQL database configuration file and file type detection. If all checks pass, you can test the SMTP or IMAP server configuration by logging into the server with your Gmail credentials and sending a test email. However, this step does not need to be performed as we will log in to the Roundcube webmail interface later using Gmail credentials. A red warning message will appear in the footer of the page, informing you that you need to delete the Roundcube installation directory after the installation process is complete, as shown in the screenshots below.

To delete the installation directory and backup the Roundcube configuration directory, run the following commands.

rm -rf /var/www/html/installer/
chown -R root:root /var/www/html/config/
chown -R 755 /var/www/html/config/

To log in to the Roundcube webmail client, open a browser and navigate to the IP address, FQDN or domain name of your server using the HTTP protocol. If you try to log in to Roundcube using your Gmail credentials, you will notice that the login process does not work. This is because Google will not allow you to sign in with your Gmail account details until you explicitly allow Less secure apps in your Google account. To enable Google Less secure apps, sign in to your Gmail account and navigate to the following link where you can enable Less secure apps (see screenshot below).


After enabling Google Less secure apps, navigate again to your server’s IP address or domain name via HTTP protocol and log in to the Roundcube webmail client using your Gmail account credentials. The login process should be successful and your Gmail messages will be displayed in Roundcube Webmail, as shown in the screenshots below.


To use the HTTPS protocol to access the Roundcube webmail interface over a secure connection, enter the following command to enable the Apache web server’s SSL module and SSL site configuration file.

a2enmod ssl
a2ensite default-ssl.conf

Next, open Apache’s default SSL configuration file with a text editor and add the following lines of code to it DocumentRoot directive, as shown in the following example:

nano /etc/apache2/sites-enabled/default-ssl.conf

Excerpt from the SSL site configuration file:

<Directory /var/www/html>
  Options +FollowSymlinks
  AllowOverride All
  Require all granted

Do not close the file yet and insert the following line of code after the SSL certificates, as shown in the following figure.

Header always set Strict-Transport-Security "max-age=15552000; includeSubdomains"

Close the SSL Apache file and make this final change to secure Roundcube and force it to redirect visitors to the HTTPS protocol every time they visit the Roundcube webmail client from their browser. Open the /etc/apache2/sites-enabled/000-default.conf file for editing and add the following rewrite rules after the DocumentRoot statement, as shown in the following example.

RewriteEngine on
RewriteCond %{HTTPS} off
RewriteRule ^(.*) https://%{HTTP_HOST}/$1


Finally, restart the Apache daemon to apply all the rules configured so far and visit or refresh the Roundcube webmail client page. Now you should be automatically redirected to the Roundcube web interface using the HTTPS protocol. Since you are using the self-signed certificate pairs issued automatically by Apache during installation, you should see an error warning in the browser. Accept the warning to continue and be redirected to the Roundcube default web interface.

systemctl restart apache2

If the UFW firewall application blocks incoming network connections to the HTTPS port, you should add a new rule to allow HTTPS traffic through the firewall by entering the following command.

ufw allow 'WWW Full'


ufw allow 443/tcp

If you are using an iptables firewall to protect your Debian system, add the following rule to allow incoming traffic through port 443 in the firewall to allow visitors to visit the Nagios Core web interface.

iptables -I INPUT -p tcp --destination-port 443 -j ACCEPT
systemctl iptables-persistent save
systemctl iptables-persistent reload

That’s it! You have successfully installed and configured Roundcube from source in Debian 9. You can now start managing your Gmail account’s emails through the Roundcube webmail client. For other custom configurations for Roundcube, visit the wiki page at the following link https://github.com/roundcube/roundcubemail/wiki

Categorized as Linux