Installing Roundcube Webmail

September 3, 2026

gentoo system-administration email php

Roundcube is a web-based IMAP email client. It connects to Dovecot for reading mail and to Postfix for sending, giving users a full webmail experience without a desktop client. This post covers installing Roundcube on Gentoo with Apache, deploying it via webapp-config, configuring the MySQL database, setting up plugins for Sieve filtering and PGP encryption, and securing the installation.

Prerequisites

Setting USE Flags

Roundcube requires several USE flags across multiple packages:

cat > /etc/portage/package.use/roundcube << 'EOF'
mail-client/roundcube mysql change-password fileinfo spell vhosts zip
EOF

cat > /etc/portage/package.use/php-roundcube << 'EOF'
dev-lang/php gd intl zip sockets spell curl exif xmlwriter jpeg
EOF

cat > /etc/portage/package.use/imagemagick-roundcube << 'EOF'
media-gfx/imagemagick -openmp jpeg tiff
EOF

The vhosts flag enables deployment via webapp-config. The PHP flags enable GD for image manipulation, intl for internationalization, spell for spell checking, and zip for attachment handling. ImageMagick is used by Roundcube for inline image processing.

Installing Roundcube

emerge -av mail-client/roundcube

If PHP USE flags changed, rebuild PHP:

emerge -uN dev-lang/php

Enabling the ImageMagick Extension

Add the imagick PHP extension to the Apache PHP configuration. Find your PHP ini file:

ls /etc/php/apache2-php*/php.ini

Add the extension before the Module Settings section:

extension=imagick.so

Deploying with webapp-config

Deploy Roundcube to a virtual host directory:

webapp-config -I -h mail.example.com -d / roundcube $(qatom -F "%{PV}" $(portageq best_visible / mail-client/roundcube))

This installs Roundcube to /var/www/mail.example.com/htdocs/.

Creating the Database

Create the Roundcube database and user:

mysql << 'EOF'
CREATE DATABASE roundcubemail CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON roundcubemail.* TO 'roundcube'@'localhost' IDENTIFIED BY 'roundcube-db-password';
FLUSH PRIVILEGES;
EOF

Import the initial schema:

mysql roundcubemail < /var/www/mail.example.com/htdocs/SQL/mysql.initial.sql

Verify the tables were created:

mysql roundcubemail -e "SHOW TABLES;"

You should see tables including users, contacts, identities, and cache.

Creating Required Directories

Roundcube needs writable directories for temporary files and logs outside the document root:

mkdir -p /var/lib/roundcube/temp
mkdir -p /var/log/roundcube
chown apache:apache /var/lib/roundcube/temp /var/log/roundcube

Configuring Roundcube

Edit /var/www/mail.example.com/htdocs/config/config.inc.php:

<?php

// Database
$config['db_dsnw'] = 'mysql://roundcube:roundcube-db-password@localhost/roundcubemail';

// IMAP
$config['imap_host'] = 'localhost:143';

// SMTP — localhost without authentication (see note below)
$config['smtp_host'] = 'localhost:25';
$config['smtp_user'] = '';
$config['smtp_pass'] = '';

// Encryption key (24 characters for default cipher)
$config['des_key'] = 'your-24-character-key-here';

// Plugins
$config['plugins'] = [
    'managesieve',
    'archive',
    'zipdownload',
    'enigma',
    'markasjunk',
    'newmail_notifier',
    'attachment_reminder',
    'identicon'
];

// Locale
$config['language'] = 'en_US';
$config['spellcheck_engine'] = 'pspell';

// Display
$config['mail_pagesize'] = 100;
$config['htmleditor'] = 1;
$config['reply_mode'] = 1;
$config['show_images'] = 2;

// Session
$config['session_lifetime'] = 480;
$config['login_rate_limit'] = 5;

// Branding
$host_parts = explode('.', $_SERVER['HTTP_HOST']);
$brand_name = (count($host_parts) > 2) ? $host_parts[count($host_parts) - 2] : $host_parts[0];
$config['product_name'] = ucfirst($brand_name) . ' Webmail';

// Disable installer
$config['enable_installer'] = false;

// Domain detection
$config['username_domain'] = '%d';

// Temp and log directories
$config['temp_dir'] = '/var/lib/roundcube/temp';
$config['log_dir'] = '/var/log/roundcube';
?>

Key Settings

$config['imap_host'] = 'localhost:143' — Roundcube connects to Dovecot on the local IMAP port. Since the connection is localhost, TLS is not needed here. The reverse proxy handles TLS for the browser connection.

$config['smtp_user'] = '' / $config['smtp_pass'] = '' — SMTP authentication is left empty because Postfix trusts connections from localhost. The standard Postfix configuration includes smtpd_sasl_exceptions_networks = 127.0.0.0/8, [::1]/128, which means Postfix doesn't advertise or accept AUTH on localhost connections. Since Roundcube connects to Postfix on localhost:25, no authentication is needed or possible. The user is already authenticated via IMAP, and Postfix enforces sender restrictions separately. If you set smtp_user = '%u' and smtp_pass = '%p', Roundcube will attempt SMTP AUTH, Postfix will reject it (AUTH not advertised), and sending will fail with an "Authentication failed" error.

$config['des_key'] — a 24-character key used to encrypt session data (including the IMAP password stored in the session). Generate a random key:

openssl rand -base64 18

$config['session_lifetime'] = 480 — sessions last 8 hours instead of the default 10 minutes. Adjust based on your security requirements.

$config['login_rate_limit'] = 5 — limits login attempts to 5 per minute per IP, reducing brute-force risk.

$config['username_domain'] = '%d' — automatically appends the domain based on the URL. If a user logs in at mail.example.com, Roundcube appends @example.com to the username.

Configuring the PGP Plugin

Roundcube's Enigma plugin provides PGP encryption and signing. Create /var/www/mail.example.com/htdocs/plugins/enigma/config.inc.php:

<?php
$config['enigma_pgp_driver'] = 'gnupg';
$config['enigma_smime_driver'] = 'phpssl';
$config['enigma_debug'] = false;
$config['enigma_pgp_homedir'] = '/opt/pgp-keys';
$config['enigma_multihost'] = true;
$config['enigma_signatures'] = true;
$config['enigma_decryption'] = true;
$config['enigma_encryption'] = true;
$config['enigma_sign_all'] = false;
$config['enigma_encrypt_all'] = false;
$config['enigma_password_time'] = 0;
?>

Create the PGP keys directory:

mkdir -p /opt/pgp-keys
chown apache:apache /opt/pgp-keys
chmod 700 /opt/pgp-keys

Users can generate and manage PGP keys through the Roundcube settings interface. Keys are stored server-side in /opt/pgp-keys.

Configuring the Apache Virtual Host

Create /etc/apache2/vhosts.d/mail.example.com.conf:

<VirtualHost *:80>
    ServerName mail.example.com

    DocumentRoot /var/www/mail.example.com/htdocs

    SetEnvIf X-Forwarded-Proto "https" HTTPS=on

    <Directory /var/www/mail.example.com/htdocs>
        Require all granted
        AllowOverride All
        Options FollowSymLinks
    </Directory>

    ErrorLog /var/log/apache2/mail.example.com_error.log
    CustomLog /var/log/apache2/mail.example.com_access.log combined
</VirtualHost>

If Apache serves Roundcube directly with TLS (not behind a reverse proxy), add an SSL virtual host:

<VirtualHost *:443>
    ServerName mail.example.com

    SSLEngine on
    SSLCertificateFile /etc/lego/example.com/certificates/mail.example.com.crt
    SSLCertificateKeyFile /etc/lego/example.com/certificates/mail.example.com.key

    DocumentRoot /var/www/mail.example.com/htdocs

    <Directory /var/www/mail.example.com/htdocs>
        Require all granted
        AllowOverride All
        Options FollowSymLinks
    </Directory>

    ErrorLog /var/log/apache2/mail.example.com_ssl_error.log
    CustomLog /var/log/apache2/mail.example.com_ssl_access.log combined
</VirtualHost>

Ensure PHP module loading is enabled in Apache:

# Verify APACHE2_OPTS includes -D PHP in /etc/conf.d/apache2
grep APACHE2_OPTS /etc/conf.d/apache2

Test and restart Apache:

apache2ctl configtest
rc-service apache2 restart

Securing the Installation

Lock Down the Installer

After initial setup, restrict access to the installer directory:

chmod 0400 -R /var/www/mail.example.com/htdocs/installer/

Restrict Configuration File Permissions

The configuration file contains database credentials:

chown root:apache /var/www/mail.example.com/htdocs/config/config.inc.php
chmod 640 /var/www/mail.example.com/htdocs/config/config.inc.php

Plugin Overview

The configured plugins provide the following functionality:

  • managesieve — manage server-side Sieve filters through the Roundcube UI under Settings > Filters. Requires Dovecot ManageSieve on port 4190.
  • archive — one-click archiving of messages to an Archive folder
  • zipdownload — download multiple messages or attachments as a ZIP file
  • enigma — PGP encryption, signing, and verification (configured above)
  • markasjunk — move messages to Junk and optionally train Rspamd via a learning script
  • newmail_notifier — browser notifications for new messages
  • attachment_reminder — warns when you mention "attach" in a message but forget to attach a file
  • identicon — generates avatar icons for contacts without profile images

Verifying the Installation

Access the Login Page

Navigate to https://mail.example.com/ in a browser. You should see the Roundcube login form.

Test Login

Log in with a mailbox created in PostfixAdmin. Enter the full email address (e.g., user@example.com) and password.

Test Sending

Compose and send a test email. Check the mail log for delivery:

tail /var/log/mail.log

Test ManageSieve

After logging in, go to Settings > Filters. If the ManageSieve plugin is working, you can create and manage Sieve filter rules through the web interface.

Verify from the Command Line

curl -sk https://mail.example.com/ | grep -o 'rcmloginuser\|Roundcube Webmail'

This confirms Roundcube's login page is being served. If you get no output, check the Apache error log and the Roundcube error log.

Check Roundcube Logs

tail -20 /var/log/roundcube/errors.log

Common issues include database connection failures, IMAP authentication errors, and file permission problems on the temp directory.

Troubleshooting Login Failures

If login fails, check the Dovecot auth log:

grep "auth" /var/log/mail.log | tail -10

Verify the IMAP connection from the server itself:

openssl s_client -connect localhost:993 -quiet

If Dovecot responds, the issue is likely in the Roundcube IMAP configuration (wrong host or port). If Dovecot doesn't respond, check the Dovecot service status.

Summary

After completing these steps:

  • Roundcube provides browser-based email access via IMAP
  • Users authenticate against Dovecot with their mailbox credentials
  • Outgoing mail is sent through Postfix with SMTP authentication
  • The ManageSieve plugin allows managing server-side Sieve filters
  • The Enigma plugin provides PGP encryption and signing
  • Sessions are encrypted with a unique key and rate-limited against brute force
  • The installer is locked down and configuration files have restricted permissions

The final step in the mail server series is testing and verifying the entire stack end-to-end.