Deploying Modoboa

Introduction

Modoboa is a comprehensive mail hosting and management platform written in Python. It provides a complete solution for managing email domains, mailboxes, and aliases through a modern web interface, while integrating seamlessly with Postfix and Dovecot for mail transport and delivery.

Built with Django, Modoboa offers an extensible plugin architecture that adds features like webmail, calendars, address books, and advanced spam filtering. The platform is designed for ISPs, hosting providers, and organizations needing professional-grade email infrastructure.

Key highlights of Modoboa:

Domain Management: Create and manage multiple email domains
Mailbox Administration: Virtual mailboxes with quotas and permissions
Alias Management: Email aliases and distribution lists
Webmail: Built-in webmail client with modern interface
Calendar/Contacts: Integrated CalDAV and CardDAV support
Spam Filtering: SpamAssassin and ClamAV integration
DKIM/SPF/DMARC: Full email authentication support
Autoresponders: Vacation messages and auto-replies
Quota Management: Storage limits per mailbox or domain
Statistics: Email traffic analytics and reporting
Multi-Tenant: Multiple administrators with delegated access
REST API: Programmatic administration
Plugin System: Extend functionality with plugins

This guide covers deploying Modoboa on Klutch.sh, configuring mail services, and managing your email infrastructure.

Why Deploy Modoboa on Klutch.sh

Deploying Modoboa on Klutch.sh provides important advantages:

Simplified Deployment: Klutch.sh builds and deploys Modoboa automatically. Push to GitHub, and your mail platform deploys.

Persistent Storage: Attach volumes for mail data, configurations, and databases that persist across updates.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure webmail and admin access.

GitHub Integration: Connect your repository for automatic deployments.

Scalable Resources: Allocate CPU and memory based on mail volume and user count.

Environment Variable Management: Securely store database credentials and mail configuration.

Custom Domains: Essential for email hosting with proper MX records and authentication.

Always-On Availability: Your mail server stays accessible 24/7.

Prerequisites

Before deploying Modoboa on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and mail server concepts
A domain with DNS control for MX records
PostgreSQL or MySQL database
(Recommended) Dedicated IP for mail sending reputation
Understanding of SPF, DKIM, and DMARC

Understanding Modoboa Architecture

Modoboa integrates with standard mail components:

Modoboa Core: Django application providing web interface and API.

Postfix: Mail Transfer Agent (MTA) for sending and receiving mail.

Dovecot: IMAP/POP3 server for mail access.

PostgreSQL/MySQL: Database for domains, users, and configuration.

SpamAssassin: Spam filtering engine.

ClamAV: Antivirus scanning for attachments.

Rspamd: Alternative modern spam filter (optional).

Preparing Your Repository

Repository Structure

modoboa-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile:

FROM modoboa/modoboa:latest

# Environment configuration
ENV MODOBOA_HOSTNAME=${MODOBOA_HOSTNAME}
ENV MODOBOA_SECRET_KEY=${MODOBOA_SECRET_KEY}
ENV MODOBOA_DEBUG=false

# Database configuration
ENV MODOBOA_DB_ENGINE=postgresql
ENV MODOBOA_DB_HOST=${MODOBOA_DB_HOST}
ENV MODOBOA_DB_NAME=${MODOBOA_DB_NAME}
ENV MODOBOA_DB_USER=${MODOBOA_DB_USER}
ENV MODOBOA_DB_PASSWORD=${MODOBOA_DB_PASSWORD}

# Admin configuration
ENV MODOBOA_ADMIN_EMAIL=${MODOBOA_ADMIN_EMAIL}
ENV MODOBOA_ADMIN_PASSWORD=${MODOBOA_ADMIN_PASSWORD}

# Create directories
RUN mkdir -p /var/vmail /var/log/modoboa

# Expose ports
# 80/443 - Web interface
# 25 - SMTP
# 587 - Submission
# 993 - IMAPS
# 995 - POP3S
EXPOSE 80 443 25 587 993 995

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`MODOBOA_HOSTNAME`	Yes	-	Primary hostname for mail server
`MODOBOA_SECRET_KEY`	Yes	-	Django secret key
`MODOBOA_DB_HOST`	Yes	-	Database server host
`MODOBOA_DB_NAME`	Yes	-	Database name
`MODOBOA_DB_USER`	Yes	-	Database username
`MODOBOA_DB_PASSWORD`	Yes	-	Database password
`MODOBOA_ADMIN_EMAIL`	Yes	-	Initial admin email
`MODOBOA_ADMIN_PASSWORD`	Yes	-	Initial admin password

Deploying Modoboa on Klutch.sh

Generate Secret Key

Create a Django secret key:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Provision Database

Set up PostgreSQL database for Modoboa.

Configure DNS Records

Set up essential DNS records:

@ MX 10 mail.yourdomain.com
mail A YOUR_SERVER_IP
@ TXT "v=spf1 mx -all"

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Modoboa deployment"
git remote add origin https://github.com/yourusername/modoboa-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “modoboa” or “mail-server”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

In deployment settings:

Select HTTP as the traffic type
Set the internal port to 80
Note: Mail ports require separate configuration

Set Environment Variables

Configure your environment:

Variable	Value
`MODOBOA_HOSTNAME`	`mail.yourdomain.com`
`MODOBOA_SECRET_KEY`	Your generated secret key
`MODOBOA_DB_HOST`	Your PostgreSQL host
`MODOBOA_DB_NAME`	`modoboa`
`MODOBOA_DB_USER`	Your database user
`MODOBOA_DB_PASSWORD`	Your database password
`MODOBOA_ADMIN_EMAIL`	`admin@yourdomain.com`
`MODOBOA_ADMIN_PASSWORD`	Your secure password

Attach Persistent Volumes

Add volumes for persistent data:

Mount Path	Recommended Size	Purpose
`/var/vmail`	100+ GB	Email storage
`/etc/modoboa`	1 GB	Configuration
`/var/log/modoboa`	5 GB	Logs

Deploy Your Application

Click Deploy to build and launch Modoboa.

Run Initial Setup

Access the web interface and complete initial configuration.

Domain and Mailbox Management

Adding Domains

Log in as administrator
Navigate to Domains
Click Add Domain
Enter domain name
Configure:
- Quota limits
- Default mailbox quota
- Enabled features

Creating Mailboxes

Navigate to Identities > Mailboxes
Click Add Mailbox
Configure:
- Email address
- Password
- Full name
- Quota
- Enabled features

Alias Management

Create email aliases:

Navigate to Identities > Aliases
Click Add Alias
Enter alias address
Add target recipients

Email Authentication

SPF Configuration

Add SPF record to DNS:

@ TXT "v=spf1 mx ip4:YOUR_IP -all"

DKIM Setup

Navigate to Admin > DKIM Keys
Generate key for domain
Add DKIM record to DNS:

selector._domainkey TXT "v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY"

DMARC Configuration

Add DMARC policy:

_dmarc TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"

Webmail Access

Accessing Webmail

Users access webmail at: https://mail.yourdomain.com/webmail/

Features include:

Email composition and management
Folder organization
Contact management
Calendar (with plugin)
Settings and filters

Mobile Configuration

Provide users with mail client settings:

IMAP Server: mail.yourdomain.com:993 (SSL)
SMTP Server: mail.yourdomain.com:587 (STARTTLS)
Username: full email address
Password: mailbox password

Spam and Security

SpamAssassin Configuration

Configure spam filtering levels:

Navigate to Admin > Parameters
Adjust spam scores
Configure actions for spam

ClamAV Integration

Enable virus scanning:

Ensure ClamAV is running
Configure in Modoboa settings
Set action for infected messages

Troubleshooting

Mail Not Sending

Verify MX records are correct
Check SPF/DKIM configuration
Review mail queue for errors
Ensure port 25 is not blocked

Mail Not Receiving

Verify MX records point to server
Check Postfix logs
Verify domain is configured in Modoboa

Authentication Failures

Check password correctness
Verify SSL/TLS settings
Review authentication logs

Webmail Issues

Clear browser cache
Check session configuration
Review Django logs

Additional Resources

Conclusion

Modoboa on Klutch.sh provides enterprise-grade email hosting with comprehensive management features. From domain and mailbox management to spam filtering and webmail access, Modoboa delivers everything needed for professional email infrastructure. The integration with standard mail components ensures reliability, while the web interface makes administration accessible. With proper DNS configuration and email authentication, you can run a secure, deliverable mail server under your control.