Deploying Mailman

Introduction

Mailman is the world’s most popular free software for managing electronic mailing lists and newsletters. Used by organizations worldwide including major open-source projects, universities, and businesses, Mailman provides comprehensive tools for managing email discussions, announcements, and group communications.

Mailman 3 represents a complete rewrite of the classic Mailman 2, featuring a modern architecture with a REST API, Django-based web interface (Postorius), and a beautiful archive browser (HyperKitty). This modular design allows for flexible deployment and easy customization.

Key highlights of Mailman:

Mailing List Management: Create and manage unlimited mailing lists
Web Interface (Postorius): Modern Django-based administration panel
Archive Browser (HyperKitty): Searchable, threaded message archives
REST API: Full API for programmatic access and integration
Moderation: Flexible message moderation with hold/approve workflows
Subscription Management: Easy subscribe/unsubscribe with confirmation
DKIM/DMARC Handling: Proper handling of modern email authentication
Templates: Customizable email templates for list communications
Plugins: Extensible architecture for custom functionality
Multi-Domain: Support for lists across multiple domains
Active Development: Regular updates from the GNU Project
Open Source: GPL licensed with decades of development

This guide walks through deploying Mailman 3 on Klutch.sh using Docker, setting up mailing lists, and managing group communications.

Why Deploy Mailman on Klutch.sh

Deploying Mailman on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the complexity of deploying Mailman’s multiple components.

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

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

GitHub Integration: Connect your configuration repository directly from GitHub.

Scalable Resources: Allocate CPU and memory based on list activity and subscriber counts.

Environment Variable Management: Securely store database credentials and secrets through Klutch.sh.

Custom Domains: Use your own domains for mailing lists.

Always-On Availability: Your mailing lists remain accessible 24/7.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Mailman configuration
Basic familiarity with Docker and containerization concepts
A domain name configured for email with MX records
An SMTP server for outgoing mail (can be local or external)
(Optional) A custom domain for your Mailman web interface

Understanding Mailman 3 Architecture

Mailman 3 uses a modular architecture:

Mailman Core: The mailing list engine handling subscription, moderation, and delivery.

Postorius: Django web interface for list administration and user settings.

HyperKitty: Web-based archive system with search and threading.

mailman-web: Combined Django application serving Postorius and HyperKitty.

Database: PostgreSQL or MySQL for storing lists, members, and archives.

Message Queue: Queue system for processing incoming and outgoing mail.

Preparing Your Repository

To deploy Mailman on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

mailman-deploy/
├── Dockerfile
├── docker-compose.yml
├── mailman-extra.cfg
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM maxking/mailman-web:0.4

# Copy custom configuration
COPY mailman-extra.cfg /etc/mailman3/mailman-extra.cfg

# Set environment variables
ENV DATABASE_TYPE=postgres
ENV SERVE_FROM_DOMAIN=lists.example.com
ENV HYPERKITTY_API_KEY=${HYPERKITTY_API_KEY}
ENV SECRET_KEY=${SECRET_KEY}

# Expose ports
EXPOSE 8000 8024

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

Mailman Core Dockerfile

For the Mailman core, use the official image:

FROM maxking/mailman-core:0.4

# Copy extra configuration
COPY mailman-extra.cfg /etc/mailman3/mailman-extra.cfg

# Expose ports
EXPOSE 8001 8024

CMD ["master", "--force"]

Configuration File

Create a mailman-extra.cfg file:

[mailman]
site_owner: admin@example.com
default_language: en

[database]
class: mailman.database.postgresql.PostgreSQLDatabase
url: postgres://mailman:password@db:5432/mailman

[mta]
incoming: mailman.mta.postfix.LMTP
outgoing: mailman.mta.deliver.deliver
lmtp_host: 0.0.0.0
lmtp_port: 8024
smtp_host: smtp
smtp_port: 25

[archiver.hyperkitty]
class: mailman_hyperkitty.Archiver
enable: yes
configuration: /etc/mailman3/mailman-hyperkitty.cfg

[webservice]
hostname: 0.0.0.0
port: 8001
admin_user: restadmin
admin_pass: ${MAILMAN_REST_PASSWORD}

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
`SECRET_KEY`	Yes	-	Django secret key
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`MAILMAN_REST_PASSWORD`	Yes	-	REST API password
`HYPERKITTY_API_KEY`	Yes	-	HyperKitty archiver API key
`SERVE_FROM_DOMAIN`	Yes	-	Domain for web interface
`SMTP_HOST`	Yes	-	Outgoing mail server

Deploying Mailman on Klutch.sh

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

Generate Secrets

Generate required secrets:

# Django secret key
python3 -c "import secrets; print(secrets.token_hex(32))"

# REST API password
openssl rand -hex 16

# HyperKitty API key
openssl rand -hex 32

Save these securely for environment variable configuration.

Configure DNS Records

Set up DNS for your mailing lists:

# MX record for list domain
lists.example.com.    MX    10 mail.example.com.

# A record for web interface
lists.example.com.    A     your-server-ip

# SPF record
lists.example.com.    TXT   "v=spf1 mx -all"

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile mailman-extra.cfg .dockerignore README.md
git commit -m "Initial Mailman deployment configuration"
git remote add origin https://github.com/yourusername/mailman-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 “mailman” or “mailing-lists”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Mailman Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8000

Set Environment Variables

In the environment variables section, add:

Variable	Value
`SECRET_KEY`	Your generated Django secret
`DATABASE_URL`	`postgres://user:pass@host/db`
`MAILMAN_REST_PASSWORD`	Your generated password
`HYPERKITTY_API_KEY`	Your generated API key
`SERVE_FROM_DOMAIN`	`lists.example.com`
`SMTP_HOST`	Your SMTP server

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/lib/mailman`	10 GB	Mailman core data
`/var/lib/mailman-web`	5 GB	Web application data
`/var/lib/mailman-web/static`	1 GB	Static files

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 Mailman containers
Provision an HTTPS certificate

Access Mailman

Once deployment completes, access the web interface at https://lists.example.com.

Initial Configuration

Creating the Superuser

Create an admin account:

mailman-web createsuperuser

Adding a Domain

Add your email domain:

Log into Postorius as superuser
Navigate to Domains
Click Add Domain
Enter domain details
Configure mail host settings

Creating Lists

Create your first mailing list:

Navigate to Lists in Postorius
Click Create New List
Enter list name and domain
Configure list settings
Save the new list

List Administration

List Settings

Configure list behavior:

Posting Policy: Open, moderated, or member-only
Subscription Policy: Open, confirm, or admin-approved
Archive Policy: Public, private, or disabled
Moderation: Hold rules and moderator assignments

Managing Members

Subscriber management:

Navigate to list settings
Click Members
Add, remove, or modify subscribers
Set member roles (owner, moderator, member)

Moderation Queue

Handle held messages:

Navigate to list settings
Click Held Messages
Review pending messages
Accept, reject, or discard

HyperKitty Archives

Browsing Archives

Access list archives:

Navigate to the archive URL
Browse by date or thread
Search across messages
View threaded discussions

Archive Settings

Configure archiving:

Per-list archive visibility
Search indexing options
Thread display settings

Integration with Mail Server

Postfix Integration

Configure Postfix for Mailman:

transport_maps = hash:/var/lib/mailman/data/postfix_lmtp

# Local delivery to Mailman
mailman_destination_recipient_limit = 1

LMTP Configuration

Mailman receives mail via LMTP:

# Mailman LMTP port
lmtp_host: 0.0.0.0
lmtp_port: 8024

Production Best Practices

Security Recommendations

Strong Secrets: Use cryptographically secure secrets
HTTPS Only: Always access web interface over HTTPS
Admin Protection: Restrict superuser access
Regular Updates: Keep Mailman updated
List Privacy: Configure appropriate visibility

Performance Optimization

Database Tuning: Optimize PostgreSQL for your load
Worker Processes: Scale web workers for traffic
Queue Processing: Monitor mail queue performance
Archive Indexing: Schedule index updates off-peak

Backup Strategy

Protect your mailing list data:

Database Backups: Regular PostgreSQL backups
Archive Backups: Back up HyperKitty archives
Configuration: Version control all configuration
Member Lists: Export member data regularly

Troubleshooting Common Issues

Mail Not Delivering

Symptoms: Messages not reaching list members.

Solutions:

Check Mailman runner logs
Verify SMTP configuration
Review mail queue status
Check member subscription status

Web Interface Errors

Symptoms: Postorius returning errors.

Solutions:

Review Django error logs
Check database connectivity
Verify static files are served
Review configuration syntax

Archive Not Updating

Symptoms: New messages not appearing in HyperKitty.

Solutions:

Check archiver connection
Verify HyperKitty API key
Review archiver logs
Manually trigger archive sync

Additional Resources

Conclusion

Deploying Mailman on Klutch.sh gives you the world’s most capable mailing list manager with modern web interfaces and searchable archives. The combination of Mailman 3’s modular architecture and Klutch.sh’s deployment simplicity means you can focus on managing your community rather than infrastructure.

With powerful moderation tools, beautiful archives via HyperKitty, and a REST API for integration, Mailman handles everything from small project mailing lists to large-scale organizational communications. Whether you’re running a community discussion list or organizational announcements, Mailman on Klutch.sh provides a reliable, feature-rich platform for email group communications.