Deploying Mail-in-a-Box

Introduction

Mail-in-a-Box is a comprehensive, self-hosted email server solution that bundles everything needed to run your own mail server into an easy-to-deploy package. It takes the complexity out of self-hosted email by automatically configuring Postfix, Dovecot, Roundcube, and dozens of other components that work together for secure, reliable email hosting.

Designed for non-experts who want to take control of their email, Mail-in-a-Box handles everything from basic email to calendars, contacts, and file synchronization. The web-based admin panel makes management straightforward, while the system automatically configures DKIM, SPF, DMARC, and other email security standards.

Key highlights of Mail-in-a-Box:

• Complete Email Solution: SMTP, IMAP, webmail, and admin interface in one package
• Roundcube Webmail: Modern webmail interface accessible from any browser
• Calendar and Contacts: CalDAV and CardDAV synchronization
• Nextcloud Integration: Built-in file sync and sharing
• Automatic Security: DKIM, SPF, DMARC, and TLS configured automatically
• DNS Server: Built-in DNS management for your mail domain
• Spam Filtering: SpamAssassin integration for spam protection
• Admin Panel: Web-based administration for users and domains
• Status Checks: System health monitoring and recommendations
• Let’s Encrypt: Automatic SSL certificate provisioning
• Backup System: Built-in encrypted backup functionality
• Open Source: CC0 public domain dedication

This guide walks through deploying Mail-in-a-Box on Klutch.sh using Docker, configuring your email domain, and managing your mail server.

Why Deploy Mail-in-a-Box on Klutch.sh

Deploying Mail-in-a-Box on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the complexity of deploying a complete mail stack.

Persistent Storage: Attach persistent volumes for mailboxes, databases, and configuration.

GitHub Integration: Connect your configuration repository directly from GitHub.

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

Custom Domains: Use your own domain with proper DNS configuration.

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

Prerequisites

Before deploying Mail-in-a-Box on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• A domain name with ability to configure DNS records
• Understanding of email protocols and deliverability requirements

Understanding Mail-in-a-Box Architecture

Mail-in-a-Box integrates many components:

Postfix: SMTP server for sending and receiving mail.

Dovecot: IMAP server for mail access and storage.

Roundcube: Web-based email client.

Nextcloud: Calendar, contacts, and file sync.

nginx: Web server and reverse proxy.

PostgreSQL: Database backend.

SpamAssassin: Spam filtering.

nsd: Authoritative DNS server.

Fail2ban: Intrusion prevention.

Preparing Your Repository

To deploy Mail-in-a-Box on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ubuntu:22.04

# Prevent interactive prompts
ENV DEBIAN_FRONTEND=noninteractive

# Install dependencies
RUN apt-get update && apt-get install -y \
    curl \
    wget \
    git \
    sudo \
    && rm -rf /var/lib/apt/lists/*

# Set environment variables
ENV PRIMARY_HOSTNAME=box.example.com
ENV NONINTERACTIVE=1

# Clone Mail-in-a-Box
RUN git clone https://github.com/mail-in-a-box/mailinabox.git /mailinabox

WORKDIR /mailinabox

# Create directories
RUN mkdir -p /home/user-data

# Expose ports
EXPOSE 25 53 53/udp 80 443 587 993 4190

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

CMD ["bash", "-c", "setup/start.sh && tail -f /var/log/syslog"]

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
PRIMARY_HOSTNAME	Yes	-	Hostname for the mail server (box.example.com)
NONINTERACTIVE	No	0	Set to 1 for non-interactive setup
SKIP_NETWORK_CHECKS	No	0	Skip network connectivity checks

Deploying Mail-in-a-Box on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Configure DNS Records

Before deployment, set up DNS records:

# NS records (point to your box)
example.com.        NS      box.example.com.

# A record for the box
box.example.com.    A       your-server-ip

# MX record
example.com.        MX  10  box.example.com.

# Additional records will be shown in admin panel

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Mail-in-a-Box deployment"
git remote add origin https://github.com/yourusername/mailinabox-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “mailinabox” or “email-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select your Mail-in-a-Box repository.

Configure Traffic

Mail-in-a-Box requires multiple ports:

• Port 25 for SMTP
• Port 53 for DNS (TCP/UDP)
• Port 80 for HTTP
• Port 443 for HTTPS
• Port 587 for Submission
• Port 993 for IMAPS
• Port 4190 for Sieve

Note: Consult Klutch.sh documentation for full port configuration.

Set Environment Variables

In the environment variables section, add:

Variable	Value
PRIMARY_HOSTNAME	box.example.com
NONINTERACTIVE	1

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/home/user-data	100+ GB	All user data, mailboxes, and databases

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Mail-in-a-Box container

Complete Initial Setup

Access https://box.example.com/admin to complete setup and create your first admin account.

Initial Configuration

Admin Panel Access

Access the admin panel at https://box.example.com/admin:

1. Create your admin email account during first login
2. This account becomes the system administrator
3. Use a strong password

DNS Configuration

The admin panel shows required DNS records:

1. Navigate to System > External DNS
2. Copy all required records
3. Configure them with your domain registrar
4. Wait for DNS propagation
5. Verify with System Status

Adding Users

Create email accounts:

1. Go to Mail > Users
2. Click Add User
3. Enter email address and password
4. Set user privileges if needed
5. Click Add User

Adding Aliases

Create email aliases:

1. Go to Mail > Aliases
2. Enter alias address
3. Enter destination address(es)
4. Click Add Alias

Using Mail Services

Webmail

Access email through Roundcube:

1. Navigate to https://box.example.com/mail
2. Log in with your email credentials
3. Full-featured webmail interface

Calendar and Contacts

Use CalDAV and CardDAV:

1. Go to https://box.example.com/cloud
2. Log in with your email credentials
3. Create calendars and contacts
4. Sync with mobile devices

Desktop Client Setup

Configure email clients:

Setting	Value
IMAP Server	box.example.com
IMAP Port	993 (SSL)
SMTP Server	box.example.com
SMTP Port	587 (STARTTLS)
Username	full email address

System Status

Health Monitoring

Check system health:

1. Navigate to System > Status Checks
2. Review all status indicators
3. Green checks indicate proper configuration
4. Address any warnings or errors

Common Status Issues

• DNS Records: Ensure all required records exist
• Reverse DNS: PTR record must match hostname
• Blacklists: Check IP reputation
• TLS Certificates: Verify certificate validity

Production Best Practices

Security Recommendations

• Strong Passwords: Enforce strong passwords for all accounts
• Regular Updates: Keep the system updated
• Monitor Logs: Review logs for suspicious activity
• Backup Encryption: Enable encrypted backups
• Access Limits: Restrict admin panel access

Deliverability

Ensure emails reach recipients:

1. PTR Record: Matching reverse DNS
2. IP Reputation: Clean IP address
3. Authentication: DKIM, SPF, DMARC configured
4. Content: Avoid spammy content
5. Volume: Gradual sending increase

Backup Strategy

Protect your email data:

1. Built-in Backups: Enable in admin panel
2. Backup Encryption: Use strong encryption password
3. Remote Storage: Configure remote backup destination
4. Regular Testing: Test backup restoration

Troubleshooting Common Issues

Mail Not Sending

Symptoms: Outgoing emails fail or bounce.

Solutions:

• Check System Status for errors
• Verify DNS records are correct
• Review mail logs for specific errors
• Check IP reputation and blacklists

Mail Not Receiving

Symptoms: Incoming emails not arriving.

Solutions:

• Verify MX records point to server
• Check spam folder for filtered messages
• Review mail logs for delivery issues
• Verify user mailbox exists

Certificate Errors

Symptoms: SSL certificate warnings.

Solutions:

• Check Let’s Encrypt status in admin
• Verify DNS A record for hostname
• Wait for certificate issuance
• Check certificate renewal logs

Webmail Not Loading

Symptoms: Cannot access Roundcube.

Solutions:

• Verify nginx is running
• Check web server logs
• Clear browser cache
• Review PHP error logs

Additional Resources

• Mail-in-a-Box Official Website
• Mail-in-a-Box Setup Guide
• Mail-in-a-Box GitHub
• Mail-in-a-Box Community Forum
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Mail-in-a-Box on Klutch.sh gives you a complete, self-hosted email solution with webmail, calendars, contacts, and file sync. The combination of Mail-in-a-Box’s all-in-one approach and Klutch.sh’s deployment platform means you can focus on using email rather than configuring dozens of mail server components.

With automatic security configuration, built-in webmail, and comprehensive admin tools, Mail-in-a-Box makes self-hosted email accessible to everyone. Whether you’re taking control of personal email or setting up email for a small organization, Mail-in-a-Box on Klutch.sh provides a reliable, feature-complete solution.