Roundcube Webmail Setup

What is Roundcube?

Roundcube is a browser-based IMAP webmail client that provides a modern, user-friendly interface for accessing email. It's perfect for self-hosted email setups and integrates seamlessly with existing mail servers like Postfix/Dovecot, Mailcow, or any standard IMAP/SMTP infrastructure.

System Requirements

PHP 7.4+ with extensions: gd, mbstring, pdo, pdo_mysql, pdo_pgsql
MySQL 5.7+ or MariaDB 10.3+
Web server: Nginx or Apache
Working IMAP server (Dovecot, Courier, etc.)
Working SMTP server (Postfix, Exim, etc.)
SQLite or database for Roundcube

Installation on Ubuntu/Debian

Via APT (Simple)

sudo apt update
sudo apt install roundcube roundcube-mysql roundcube-plugins

During installation, select MySQL and enter credentials for the database setup.

Manual Installation

Download the latest version:

cd /var/www
wget https://github.com/roundcube/roundcubemail/releases/download/1.6.7/roundcubemail-1.6.7-complete.tar.gz
tar xzf roundcubemail-1.6.7-complete.tar.gz
mv roundcubemail-1.6.7 roundcube
cd roundcube
cp config/config.inc.php.sample config/config.inc.php
chown -R www-data:www-data .

Create database:

mysql -u root -p < SQL/mysql.initial.sql

Database Setup

Create dedicated user and database in MySQL:

CREATE DATABASE roundcube;
CREATE USER 'roundcube'@'localhost' IDENTIFIED BY 'securerdpass123!';
GRANT ALL PRIVILEGES ON roundcube.* TO 'roundcube'@'localhost';
FLUSH PRIVILEGES;

Import schema:

mysql -u roundcube -p roundcube < /var/www/roundcube/SQL/mysql.initial.sql

Configuration

Edit /etc/roundcube/config.inc.php or /var/www/roundcube/config/config.inc.php:

<?php
// Database connection
$config['db_dsnw'] = 'mysql://roundcube:securerdpass123!@localhost/roundcube';

// IMAP settings
$config['default_host'] = 'imap.example.com';
$config['default_port'] = 993;
$config['imap_conn_options'] = array(
    'ssl' => array(
        'verify_peer' => false,
        'verify_peer_name' => false,
    ),
);

// SMTP settings
$config['smtp_server'] = 'smtp.example.com';
$config['smtp_port'] = 587;
$config['smtp_user'] = '%u';  // Username from IMAP login
$config['smtp_pass'] = '%p';  // Password from IMAP login
$config['smtp_auth_type'] = 'LOGIN';

// Enable STARTTLS
$config['smtp_conn_options'] = array(
    'ssl' => array(
        'verify_peer' => false,
        'verify_peer_name' => false,
    ),
);

// DES key for session encryption (generate with: openssl rand -base64 24)
$config['des_key'] = 'abcdef1234567890!@#$%^';

// UI settings
$config['product_name'] = 'DeluxHost Webmail';
$config['support_url'] = 'https://support.deluxhost.com';
$config['language'] = 'en_US';

// Plugins
$config['plugins'] = array(
    'archive',
    'zipdownload',
    'managesieve',
    'password',
    'markasjunk',
    'contextmenu',
);

// Password plugin settings
$config['password_driver'] = 'ssha';  // Or 'ldap', 'poppassd', 'directadmin'
$config['password_ssha_pwgen_method'] = 'openssl';
$config['password_ssha_hash'] = 'SHA256';

// Allow multiple IMAP/SMTP hosts
$config['imap_host_override'] = false;
$config['imap_auth_type'] = 'check';

// Message size limit (bytes)
$config['max_message_size'] = '50M';

?>

Nginx Configuration with PHP-FPM

Create /etc/nginx/sites-available/roundcube:

upstream php_fpm {
    server unix:/run/php/php8.1-fpm.sock;
}

server {
    listen 80;
    listen [::]:80;
    server_name mail.example.com webmail.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name mail.example.com webmail.example.com;

    root /var/www/roundcube;
    index index.php;

    ssl_certificate /etc/letsencrypt/live/mail.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mail.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 50M;

    # Deny access to config and sensitive files
    location ~ ^/(config|temp|logs|installer)/ {
        deny all;
    }

    location ~ \.php$ {
        fastcgi_pass php_fpm;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_param SCRIPT_NAME $fastcgi_script_name;
    }

    # Serve static assets
    location ~* \.(js|css|png|jpg|gif|ico|svg|woff|woff2|ttf)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Disable direct access to hidden files
    location ~ /\. {
        deny all;
    }

    # Security headers
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/roundcube /etc/nginx/sites-enabled/
sudo systemctl reload nginx

Enable Essential Plugins

Plugin configurations in config/config.inc.php:

Archive Plugin

Auto-archives messages to yearly folders:

$config['archive_mbox'] = 'Archive';

Zipdownload Plugin

Download multiple messages as ZIP:

$config['zipdownload_selection'] = true;

ManageSieve Plugin

Create server-side filters (requires ManageSieve on IMAP server):

$config['managesieve_host'] = 'imap.example.com';
$config['managesieve_port'] = 4190;

Password Plugin

Allow users to change their mail password:

// For LDAP backend
$config['password_driver'] = 'ldap';
$config['password_ldap_host'] = 'ldap.example.com';
$config['password_ldap_basedn'] = 'dc=example,dc=com';

// For Dovecot SSHA
$config['password_driver'] = 'ssha';
$config['password_ssha_pwgen_method'] = 'openssl';

SMTP Authentication Methods

Option 1: STARTTLS (Port 587)

$config['smtp_server'] = 'smtp.example.com';
$config['smtp_port'] = 587;
$config['smtp_conn_options'] = array(
    'ssl' => array(
        'verify_peer'      => false,
        'verify_peer_name' => false,
    ),
);

Option 2: SSL/TLS (Port 465)

$config['smtp_server'] = 'tls://smtp.example.com';
$config['smtp_port'] = 465;

Option 3: No Encryption (Port 25 - Not Recommended)

$config['smtp_server'] = 'smtp.example.com';
$config['smtp_port'] = 25;

Integration with Mail Servers

Postfix + Dovecot

Roundcube works seamlessly with standard Postfix/Dovecot setups. Configure IMAP and SMTP to point to your Dovecot and Postfix instances:

$config['default_host'] = 'localhost';  // Dovecot IMAP
$config['smtp_server'] = 'localhost';   // Postfix SMTP

Mailcow

When using Mailcow, point to the internal hostname:

$config['default_host'] = 'mailcow.example.com';
$config['smtp_server'] = 'mailcow.example.com';

Navigate to https://mail.example.com
Enter email address and password
Roundcube automatically detects IMAP/SMTP settings
Once logged in, configure personal settings:
- Language and timezone
- Display preferences
- Signature
- Identity details

User Features

Address Book

Import/export contacts
Create contact groups
LDAP directory support

Identities

Create multiple sender addresses
Set reply-to and organization
Use different signatures per identity

Filters (ManageSieve)

Server-side email rules:

Go to Settings → Filters
Create new filter (requires ManageSieve plugin)
Define conditions and actions (move, delete, forward, etc.)
Rules execute on server (works offline)

Updating Roundcube

Via APT

sudo apt update
sudo apt upgrade roundcube

Manual Update

Backup current installation:

sudo cp -r /var/www/roundcube /var/www/roundcube.backup

Download new version:

cd /tmp
wget https://github.com/roundcube/roundcubemail/releases/download/1.6.8/roundcubemail-1.6.8-complete.tar.gz
tar xzf roundcubemail-1.6.8-complete.tar.gz

Copy new files:

sudo cp -r roundcubemail-1.6.8/* /var/www/roundcube/

Run database migrations:

cd /var/www/roundcube
sudo php bin/updatedb.sh --version=latest

Restart PHP-FPM:
```
sudo systemctl restart php8.1-fpm
```

Security Considerations

When using Roundcube with external email servers, ensure:

All connections use TLS/SSL (avoid plain IMAP/SMTP)
Use strong passwords or app-specific passwords
Restrict access to trusted networks if possible
Keep PHP and plugins updated
Regularly back up the database
Use fail2ban to prevent brute-force attacks

Troubleshooting

Connection to IMAP Server Failed

Check PHP error logs and verify IMAP/SMTP settings:

tail -f /var/log/php8.1-fpm.log

Test IMAP connectivity:

openssl s_client -connect imap.example.com:993

Blank Screen or 500 Error

Check Nginx logs:

tail -f /var/log/nginx/error.log

Ensure config/ directory has proper permissions:

sudo chown -R www-data:www-data /var/www/roundcube/config

Password Changes Not Working

Verify ManageSieve is running (if using sieve filters) or password driver is configured correctly.

For Dovecot SSHA passwords, ensure dovecot-sieve package is installed on mail server.

On this page