Deploying Mox

Introduction

Mox is a modern, all-in-one open-source mail server written in Go. Unlike traditional mail stacks that require configuring multiple components (Postfix, Dovecot, SpamAssassin), Mox provides everything in a single binary, making deployment and maintenance significantly simpler while maintaining security and performance.

Designed with modern email standards and security in mind, Mox implements SPF, DKIM, DMARC, DANE, MTA-STS, and TLS-RPT out of the box. The integrated approach reduces configuration complexity while ensuring your mail server follows best practices for deliverability and security.

Key highlights of Mox:

• All-in-One: SMTP, IMAP, webmail, admin panel in single binary
• Modern Security: SPF, DKIM, DMARC, DANE, MTA-STS, TLS-RPT built-in
• Automatic HTTPS: Let’s Encrypt integration for TLS certificates
• Built-in Webmail: Modern web interface for email access
• Spam Filtering: Junk filtering with training capabilities
• Auto-Configuration: Supports Thunderbird/Outlook auto-discover
• Metrics: Prometheus metrics for monitoring
• JMAP Support: Modern email protocol support
• Storage Quotas: Per-account storage limits
• Simple Configuration: YAML-based configuration
• Low Resource Usage: Efficient Go implementation
• Active Development: Regular updates and improvements

This guide covers deploying Mox on Klutch.sh, configuring DNS, and setting up your mail server.

Why Deploy Mox on Klutch.sh

Deploying Mox on Klutch.sh provides significant advantages:

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

Persistent Storage: Attach volumes for mail data, configurations, and databases.

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

GitHub Integration: Connect your repository for automatic deployments.

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

Environment Variable Management: Securely store configuration values.

Custom Domains: Essential for proper mail server operation with your domain.

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

Prerequisites

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

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

Understanding Mox Architecture

Mox integrates all mail components:

SMTP Server: Handles inbound and outbound mail (ports 25, 465, 587).

IMAP Server: Provides mail access for clients (ports 993, 143).

Webmail: Built-in web interface for browser access.

Admin Panel: Web-based configuration and monitoring.

JMAP Server: Modern email protocol for compatible clients.

Metrics Endpoint: Prometheus-compatible monitoring.

All components run in a single Go binary with a unified configuration.

Preparing Your Repository

Repository Structure

mox-deploy/
├── Dockerfile
├── mox.conf
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile:

FROM golang:1.21-alpine AS builder

RUN apk add --no-cache git

WORKDIR /build
RUN git clone https://github.com/mjl-/mox.git .
RUN CGO_ENABLED=0 go build -o mox

FROM alpine:latest

RUN apk add --no-cache ca-certificates tzdata

COPY --from=builder /build/mox /usr/local/bin/mox

# Create directories
RUN mkdir -p /mox/data /mox/config

WORKDIR /mox

# Environment variables
ENV MOX_DOMAIN=${MOX_DOMAIN}
ENV MOX_HOSTNAME=${MOX_HOSTNAME}
ENV MOX_ADMIN_PASSWORD=${MOX_ADMIN_PASSWORD}

# Expose ports
# 25 - SMTP
# 465 - SMTPS
# 587 - Submission
# 993 - IMAPS
# 443 - HTTPS (webmail/admin)
# 80 - HTTP (ACME challenges)
EXPOSE 25 465 587 993 443 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget -q --spider http://localhost:80/ || exit 1

# Start Mox
CMD ["mox", "serve"]

Environment Variables Reference

Variable	Required	Default	Description
MOX_DOMAIN	Yes	-	Primary email domain
MOX_HOSTNAME	Yes	-	Mail server hostname
MOX_ADMIN_PASSWORD	Yes	-	Admin panel password
MOX_LISTENER_IPS	No	-	IPs to listen on
MOX_ACME_EMAIL	No	-	Email for Let’s Encrypt

Deploying Mox on Klutch.sh

Generate Admin Password

Create a secure admin password:

openssl rand -base64 24

Configure DNS Records

Set up required DNS records for your domain:

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

Additional records will be generated by Mox during setup.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Mox deployment"
git remote add origin https://github.com/yourusername/mox-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 “mox” or “mail”.

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 443 or 80
• Note: Mail ports require additional configuration

Set Environment Variables

Configure your environment:

Variable	Value
MOX_DOMAIN	yourdomain.com
MOX_HOSTNAME	mail.yourdomain.com
MOX_ADMIN_PASSWORD	Your secure password

Attach Persistent Volumes

Add volumes for persistent data:

Mount Path	Recommended Size	Purpose
/mox/data	100+ GB	Mail storage and database
/mox/config	1 GB	Configuration files

Deploy Your Application

Click Deploy to build and launch Mox.

Complete Initial Setup

Run the quick setup command:

mox quickstart admin@yourdomain.com

Configure DNS from Output

Mox will output required DNS records. Add these to your domain:

• DKIM records
• DMARC record
• MTA-STS records
• TLSRPT record

Access Admin Panel

Navigate to https://mail.yourdomain.com/admin/.

Using Mox

Accessing Webmail

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

Features include:

• Read and compose emails
• Folder management
• Search functionality
• Settings and filters

Creating Accounts

Add new email accounts:

mox config account add username

Or through the admin panel:

1. Access admin interface
2. Navigate to Accounts
3. Click Add Account
4. Set username and password

Configuring Mail Clients

Provide users with settings:

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

Auto-configuration works for Thunderbird and Outlook.

Email Authentication

SPF Record

Mox generates the recommended SPF record:

@ TXT "v=spf1 mx -all"

DKIM

DKIM is automatically configured. Add the generated DNS records:

mox._domainkey TXT "v=DKIM1; k=ed25519; p=..."

DMARC

Add the DMARC policy:

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

MTA-STS

Mox supports MTA-STS for secure mail transport:

1. Add MTA-STS DNS record
2. Host policy file at /.well-known/mta-sts.txt

Spam Filtering

Junk Training

Train the spam filter:

1. Move spam to Junk folder
2. Move legitimate mail out of Junk
3. Filter learns from classifications

Blocklists

Configure DNS blocklists in settings to block known spam sources.

Monitoring

Admin Dashboard

The admin panel shows:

• Queue status
• Recent deliveries
• Error logs
• Connection statistics

Prometheus Metrics

Export metrics for monitoring:

• Mail queue length
• Delivery success/failure rates
• Connection counts
• Resource usage

Troubleshooting

Mail Not Delivering

• Check MX records are correct
• Verify SPF/DKIM/DMARC configuration
• Review delivery logs
• Check IP reputation

Authentication Failures

• Verify password is correct
• Check TLS configuration
• Review authentication logs

Certificate Issues

• Ensure ACME can reach port 80
• Check Let’s Encrypt rate limits
• Verify domain points to server

High Spam

• Train junk filter more
• Enable additional blocklists
• Review DMARC reports

Additional Resources

• Mox GitHub Repository
• Mox Documentation
• Learn DMARC
• MX Toolbox
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Mox on Klutch.sh provides a modern, secure mail server in a single deployment. The all-in-one approach eliminates the complexity of traditional mail stacks while implementing best practices for email security and deliverability. With built-in webmail, automatic certificate management, and comprehensive email authentication, Mox delivers a complete mail solution. Klutch.sh handles the deployment complexity, letting you focus on running a reliable mail server.