Install and Run Modoboa Email Server on Debian VPS (Complete Guide)

This article provides a guide to install and run Modoboa email server on Debian VPS.

Step-by-Step Guide to Install and Run Modoboa on a Debian VPS

Modoboa is a complete mail hosting and management platform that simplifies the deployment of email services. Here’s a step-by-step guide to install and run Modoboa on a Debian VPS.

Prerequisites

Before starting, ensure the following:

1. A VPS running Debian (Debian 11 “Bullseye” or Debian 12 “Bookworm” is recommended).
2. A fully qualified domain name (FQDN) configured for your VPS (e.g., mail.yourdomain.com).
3. Root access or a user with sudo privileges.
4. Port 25 open for outbound traffic (verify with your hosting provider if blocked).

Install and Run Modoboa Email Server on Debian VPS

To install and run Modoboa email server on Debian VPS, follow the steps below:

1. Update the System

   1. Log in to your Debian VPS:

      ssh user@your-server-ip

   2. Update your package list and upgrade installed packages:

      sudo apt update && sudo apt upgrade -y

2. Configure DNS Records

   To host an email server, set up the necessary DNS records for your domain:

   1. A Record: Point mail.yourdomain.com to your VPS IP.
   2. MX Record: Set your domain’s mail server to mail.yourdomain.com.
   3. SPF Record: Add an SPF TXT record (example):

      "v=spf1 mx -all"

   4. DKIM Record: This will be generated later by Modoboa.
   5. DMARC Record: Optional but recommended (example):

      "v=DMARC1; p=none; rua=mailto:dmarc-reports@yourdomain.com"

3. Install Dependencies

   1. Install basic dependencies:

      sudo apt install -y git curl wget gnupg2 lsb-release

   2. Install Python and pip:

      sudo apt install -y python3 python3-pip python3-venv

   3. Install database server (PostgreSQL):

      sudo apt install -y postgresql

4. Install Modoboa Installer

   The Modoboa installer simplifies setup.

   1. Install the installer:

      pip3 install modoboa-installer

   2. Verify the installation:

      modoboa-installer --version

5. Prepare the Installation Directory

   1. Create a directory for Modoboa:

      mkdir -p ~/modoboa && cd ~/modoboa

   2. Download the Modoboa configuration:

      modoboa-installer init mail.yourdomain.com

   3. Edit the configuration file (optional):

      nano installer.cfg

6. Run the Installer

   1. Start the installation:

      modoboa-installer deploy mail.yourdomain.com

   2. The script will:
      • Install and configure Nginx as the web server.
      • Install and configure Postfix and Dovecot for SMTP and IMAP.
      • Set up Let’s Encrypt SSL certificates (ensure your domain points to the VPS).
   3. Monitor the output for errors and follow any provided instructions.

7. Configure Modoboa

   1. Access the Modoboa web interface:
      • Open your browser and navigate to https://mail.yourdomain.com.
      • Login with the default admin credentials:
        • Username: admin
        • Password: password (change immediately after logging in).
   2. Configure your mail domains and user accounts.

8. Test Email Services

   1. Send a test email to an external address (e.g., Gmail) to verify outbound mail.
   2. Use an external email to reply back and verify inbound mail.
   3. Check your domain’s DNS records using online tools like MXToolbox to ensure no configuration issues.

9. Optimize and Secure

   1. Enable Fail2Ban to protect against brute force attacks:

      sudo apt install -y fail2ban

   2. Configure Firewall (UFW):

      sudo apt install -y ufw sudo ufw allow OpenSSH sudo ufw allow 25,80,443,587,993/tcp sudo ufw enable

   3. Monitor logs:
      • Check mail logs:

        sudo tail -f /var/log/mail.log

      • Check Modoboa logs:

        sudo journalctl -u modoboa

10. Regular Maintenance

    1. Update the system and Modoboa regularly:

       sudo apt update && sudo apt upgrade -y pip3 install --upgrade modoboa-installer

    2. Backup your data:
       • Backup the database and configuration files periodically.

Troubleshooting

• If emails are marked as spam, check your SPF, DKIM, and DMARC records.
• Verify Modoboa logs for configuration issues.
• Ensure ports required for email services (e.g., 25, 587, 993) are open.

By following these steps, you’ll have a fully operational Modoboa mail server on your Debian VPS.

Initial Configuration After Modoboa Installation

After successfully installing Modoboa and logging in to the web interface, follow these steps for initial configuration to ensure your mail server is fully operational and secure.

1. Change Default Admin Password

   1. Log in to the Modoboa Admin interface at https://mail.yourdomain.com with the default credentials:
      • Username: admin
      • Password: password
   2. Navigate to the “Account” section in the top-right dropdown menu.
   3. Change the password to something secure:
      • Use a combination of uppercase, lowercase, numbers, and special characters.

2. Add a Mail Domain

   1. Go to the “Domains” section in the admin dashboard.
   2. Click on “Add domain” and provide the following details:
      • Domain name: Enter your domain (e.g., yourdomain.com).
      • Default mail server address: This will typically be mail.yourdomain.com.
      • Options:
        • Enable Domain alias if needed (e.g., example.org as an alias for example.com).
        • Enable DKIM signing (recommended).
   3. Save the domain.

3. Generate DKIM Keys

   If you enabled DKIM signing:

   1. Go to “Domains” > “DNS” for the newly added domain.
   2. Copy the DKIM public key provided in the interface.
   3. Add a TXT record to your domain’s DNS with the following details:
      • Name: dkim._domainkey.yourdomain.com
      • Value: Paste the DKIM public key.
      • TTL: Set to 3600 seconds (or default).
   4. Wait for DNS propagation (this may take a few hours).

4. Configure Mail Users

   1. Navigate to the “Users” section in the admin dashboard.
   2. Click “Create” to add a new user:
      • Username: The email address (e.g., user@yourdomain.com).
      • First name/Last name: User’s name.
      • Role: Choose SimpleUser for regular email users.
      • Password: Set a secure password or allow the system to generate one.
   3. Save the user and repeat for additional accounts.

5. Test Sending and Receiving Emails

   1. Log in to the webmail interface as a test user:
      • Navigate to https://mail.yourdomain.com/webmail.
   2. Send a test email to an external address (e.g., Gmail or Yahoo).
   3. Check for the email’s arrival in the recipient’s inbox (not spam). If the email goes to spam:
      • Verify SPF, DKIM, and DMARC records in your DNS settings.
      • Use tools like MXToolbox or Mail Tester to check email reputation and DNS setup.
   4. Reply to the test email to ensure inbound email functionality.

6. Set Up SPF and DMARC Records

   1. Add the following TXT records to your DNS configuration:
      • SPF Record:

        Name: @ Value: v=spf1 mx -all TTL: 3600

        This specifies that only your mail server is authorized to send emails for your domain.

      • DMARC Record (optional but recommended):

        Name: _dmarc Value: v=DMARC1; p=none; rua=mailto:dmarc-reports@yourdomain.com TTL: 3600

   2. Wait for DNS changes to propagate.

7. Set Up Mail Relay (Optional)

   If your hosting provider blocks outbound port 25, use a mail relay service:

   1. Sign up for a relay service like Mailgun or SendGrid.
   2. Configure the relay in Postfix by editing the configuration file:

      sudo nano /etc/postfix/main.cf

   3. Add the relay settings (replace with your service credentials):

      relayhost = [smtp.mailgun.org]:587 smtp_sasl_auth_enable = yes smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd smtp_sasl_security_options = noanonymous smtp_tls_security_level = encrypt smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt

   4. Create the sasl_passwd file:

      sudo nano /etc/postfix/sasl_passwd

      Add your relay credentials:

      [smtp.mailgun.org]:587 username:password

   5. Apply the configuration:

      sudo postmap /etc/postfix/sasl_passwd sudo systemctl restart postfix

8. Enable SSL/TLS

   Ensure all email connections are encrypted:

   1. Modoboa installs Let’s Encrypt certificates automatically.
   2. Verify SSL/TLS status:
      • Check /etc/nginx/sites-enabled/mail.yourdomain.com for SSL configuration.
      • Use online tools like SSL Labs to test your SSL setup.

9. Configure Auto-Renewal for Let’s Encrypt

   1. Verify that the Certbot renewal cron job is set:

      sudo systemctl list-timers | grep certbot

   2. Test manual renewal:

      sudo certbot renew --dry-run

10. Monitor and Maintain the Server

    1. Regularly check email logs:

       sudo tail -f /var/log/mail.log

    2. Backup critical data:
       • Mail data: /var/mail/
       • Modoboa settings and database.
    3. Update Modoboa and dependencies:

       pip3 install --upgrade modoboa

By completing these steps, you’ll have a fully configured and operational Modoboa email server.

Integrate the modoboa-webmail Extension with a Modoboa Server

The modoboa-webmail extension provides webmail functionality to Modoboa, enabling users to send, receive, and manage emails directly from the Modoboa interface. Here’s how you can integrate and configure the extension on your Modoboa server:

1. Verify Prerequisites

   1. Modoboa Installed: Ensure you have Modoboa installed and running properly.
   2. Python and Pip: Confirm that pip and Python3 are installed on your server:

      python3 --version pip3 --version

   3. Database Backups: Create a backup of your Modoboa database and critical data before proceeding.

2. Install the modoboa-webmail Extension

   1. Activate the Python virtual environment used by Modoboa:

      source /srv/modoboa/env/bin/activate

   2. Install the modoboa-webmail extension using pip:

      pip install modoboa-webmail

   3. Verify the installation:

      pip show modoboa-webmail

3. Step 3: Update Modoboa Configuration

   1. Add the modoboa-webmail extension to Modoboa’s configuration:
      • Locate the settings.py file for Modoboa, typically found in /srv/modoboa/instance/instance/settings.py.
      • Open the file with a text editor:

        nano /srv/modoboa/instance/instance/settings.py

      • Add the extension to the INSTALLED_APPS list:

        python INSTALLED_APPS += ( "modoboa_webmail", )

   2. Save and exit the file.

4. Apply Database Migrations

   Run migrations to add the necessary database tables for the modoboa-webmail extension:

   python manage.py migrate

5. Collect Static Files

   Gather static files required by the webmail extension:

   python manage.py collectstatic --noinput

6. Restart Services

   1. Restart the Modoboa instance to apply changes:

      systemctl restart uwsgi

   2. Restart the Nginx service to reload configuration (if applicable):

      systemctl restart nginx

7. Enable and Configure Webmail in Modoboa

   1. Log in to the Modoboa Admin interface at https://mail.yourdomain.com.
   2. Navigate to “Extensions” in the admin dashboard.
   3. Locate modoboa-webmail in the list of extensions and activate it.
   4. Configure the webmail settings:
      • Default IMAP settings:
        • Host: mail.yourdomain.com
        • Port: 993
        • SSL: Enabled
      • Default SMTP settings:
        • Host: mail.yourdomain.com
        • Port: 587
        • TLS: Enabled

8. Test Webmail Functionality

   1. Log in to the Modoboa web interface with a user account (not admin).
   2. Access the “Webmail” tab in the navigation bar.
   3. Send a test email to verify outbound functionality.
   4. Receive a test email to confirm inbound functionality.

9. Troubleshooting

   1. Check Logs: If you encounter issues, review the logs for detailed error messages:
      • Modoboa logs:

        sudo journalctl -u uwsgi

      • Email service logs:

        sudo tail -f /var/log/mail.log

   2. Verify DNS Records:
      • Confirm SPF, DKIM, and DMARC are correctly configured to avoid email delivery issues.
   3. Debug IMAP/SMTP Settings:
      • Use tools like openssl or telnet to verify connectivity:

        openssl s_client -connect mail.yourdomain.com:993

10. Optional: Customize Webmail Appearance

    1. Modify the webmail interface by editing theme settings or CSS files:
       • Locate the webmail static files directory:
         /srv/modoboa/instance/static/modoboa_webmail/
    2. Make the desired changes and re-run collectstatic to apply.

By completing these steps, the modoboa-webmail extension will be fully integrated and functional on your Modoboa server, allowing users to manage their emails directly through the Modoboa web interface.

Steps to Add modoboa-radicale to Your Modoboa Server

The modoboa-radicale extension integrates a CalDAV and CardDAV server (Radicale) into your Modoboa instance, enabling calendar and contact synchronization. Below is a step-by-step guide to install and configure it.

1. Prerequisites

   1. Ensure Modoboa is Installed: You must have a functioning Modoboa instance.
   2. Python Virtual Environment: You should be using a virtual environment for Modoboa (typically located in /srv/modoboa/env).
   3. Backup Your System: Create a backup of your Modoboa database and configuration before proceeding.

2. Install Radicale

   1. Install Radicale from the Debian repositories:

      sudo apt install radicale

   2. Verify Radicale installation:

      radicale --version

3. Install the modoboa-radicale Extension

   1. Activate the Python virtual environment for Modoboa:

      source /srv/modoboa/env/bin/activate

   2. Install the modoboa-radicale extension:

      pip install modoboa-radicale

   3. Verify the installation:

      pip show modoboa-radicale

4. Update Modoboa Configuration

   1. Add the modoboa-radicale extension to the Modoboa configuration file:
      • Open settings.py (located at /srv/modoboa/instance/instance/settings.py):

        nano /srv/modoboa/instance/instance/settings.py

      • Add modoboa_radicale to the INSTALLED_APPS list:

        python INSTALLED_APPS += ( "modoboa_radicale", )

   2. Save and close the file.

5. Apply Database Migrations

   Run the migrations to add database tables for the modoboa-radicale extension:

   python manage.py migrate

6. Collect Static Files

   Gather static files for the modoboa-radicale extension:

   python manage.py collectstatic --noinput

7. Configure Radicale

   1. Modify the Radicale configuration file (/etc/radicale/config):

      sudo nano /etc/radicale/config

   2. Update the configuration with the following settings:

      [server] hosts = 0.0.0.0:5232 base_prefix = /radicale/ [auth] type = none [storage] filesystem_folder = /var/lib/radicale/collections

   3. Save the file and restart the Radicale service:

      sudo systemctl restart radicale

8. Enable and Configure the Extension in Modoboa

   1. Log in to the Modoboa Admin interface at https://mail.yourdomain.com.
   2. Go to Extensions > modoboa-radicale and activate it.
   3. Configure default settings for calendars and contacts:
      • URL: http://127.0.0.1:5232/radicale/

9. Test Radicale Integration

   1. Log in to the Modoboa web interface with a user account.
   2. Navigate to Settings > Calendar/Contacts to verify access to CalDAV and CardDAV services.

10. Optional: Enable SSL for Radicale

    If you want to secure the Radicale server:

    1. Edit the Radicale configuration to enable SSL:

       [server] ssl = True certificate = /etc/letsencrypt/live/mail.yourdomain.com/fullchain.pem key = /etc/letsencrypt/live/mail.yourdomain.com/privkey.pem

    2. Restart the Radicale service:

       sudo systemctl restart radicale

    3. Update the Radicale URL in Modoboa to https://mail.yourdomain.com/radicale/.

11. Sync Calendars and Contacts

    1. Use a CalDAV/CardDAV client (e.g., Thunderbird, Outlook, iOS, or Android) to sync data:
       • CalDAV URL: https://mail.yourdomain.com/radicale/user@example.com/calendar/
       • CardDAV URL: https://mail.yourdomain.com/radicale/user@example.com/addressbook/
       • Username: Your Modoboa email address.
       • Password: Your Modoboa account password.
    2. Test synchronization for both calendars and contacts.

12. Monitor and Maintain

    1. Check Radicale logs for errors:

       sudo journalctl -u radicale

    2. Regularly update Modoboa and its extensions:

       pip install --upgrade modoboa-radicale

By following these steps, you’ll successfully integrate and configure modoboa-radicale with your Modoboa server, enabling seamless calendar and contact synchronization.

Conclusion

You now know how to install and run Modoboa email server on Debian VPS. Additionally, you have followed initial configuration steps and modoboa-webmail and modoboa-radicale integrations.

Provide your feedback in the comments below!