Skip to content

Home

Jump to bottom
Thilo Fromm edited this page Dec 14, 2023 · 22 revisions

Welcome to 'Mailserver' - a no pain, minimal configuration, full-featured mail server.

This project provides a full-featured email server with a strong focus on simplified set-up and ease of operation.

Features included are:

  • SMTP[s] and IMAP[s] servers, with managesieve for server-side IMAP filtering
  • Fully automated set-up based on very few settings
    • certificates generation is automated, as is renewal (just restart the service)
    • SPF, DKIM, and DMARC integrated by default - helpers are available to guide you through DNS set-up
    • Fail2Ban integrated to auto-ban offending IP addresses based on mail server log entries
    • Basic user handling (add/list/delete, change password, manage aliases)
  • Optional monitoring suite with "landing page" summary dashboard as well as detailed dashboards for SMTP server, IMAP server, Fail2Ban, and DNS sanity

NOTE: Mailserver 1.2.0 introduces breaking changes and needs manual migration when upgrading from 1.1.3 or lower. If you are upgrading, please read "Migrating from Mailserver 1.1.3 or lower to to Mailserver 1.2.0" at the bottom of this document.

Requirements

For the base mailserver

  • An internet connected server, ideally one you control reverse DNS (PTR record) for. PTR is not a requirement but a strong recommendation - if you don't have control over PTR you're more likely to be classified as spammer.

  • Control over a domain to serve mails for, as well as a hostname to point to your server's IP

  • About 1GB of RAM (less RAM wasn't tested; please let us know if you use mailserver with less!)

  • 10GB of storage (total - for OS, containers, and mailboxes)

  • While single core machines will work, 2 cores are recommended.

For the monitoring suite

  • 2 cores or more
  • 2GB - 4GB of RAM
  • 15GB of storage (prometheus & pushgateway state)

If you run additional services (like e.g. the mailman3 contrib) aim for 4GB rather than 2GB of RAM.

Set up the mail server

To get started, you'll need an internet-connected server as well as a DNS name pointing to it. DNS is a requirement for getting letsencrypt certificates.

See the set-up instructions for more.

Operate the mail server

Operations docs include day-to-day tasks like adding and removing users, managing aliases, changing users' passwords etc. It also includes backup and restore instructions, and there's a section on importing existing mailboxes. The documentation also covers renewing letsencrypt certificates. See the operations instructions for details.

Mail client settings

The server supports plain SMTP (enforces STARTTLS), SMTP over SSL, IMAP, and IMAP over SSL.

  • The server name (for both sending and receiving) is HOSTNAME.
  • SMTP:
    • Port 25 w/ STARTTLS
    • Port 465 w/ SSL/TLS
  • IMAP:
    • Port 143 (STARTTLS)
    • Port 993 w/ SSL/TLS

Either "plain" or "login" login is supported. Username is the full user@domain name supplied to user.sh add .... Password is the password provided (or generated).

Mailserver architecture

This discusses internal services, file system layout, and related information.

The Mailserver includes pre-configured services:

  • Postfix for handling SMTP[S]
  • Dovecot for IMAP[S]
  • Caddy for HTTP (letsencrypt) and optionally HTTPS for monitoring / Grafana
  • Fail2ban for monitoring Postfix, Dovecot, and (optionally) Grafana logs. Fail2ban runs inside the Mailserver container in a separate network namespace and therefore should not affect connections on the Host.

More details are available on the Mailserver architecture page.

Monitoring suite

The Mailserver ships with an optional, comprehensive monitoring suite to monitor all included services. The suite uses stock Grafana and Prometheus containers and wires these up to the mailserver container. A Pushserver is included to allow the mailserver container to publish additional statistics from a script.

The monitoring containers only connect to a private network to access the mailserver metrics. Caddy, the HTTP server in the mailserver container, proxies HTTPS to Grafana. The monitoring containers are otherwise not internet accessible, nor can the containers access the internet.

A number of pre-configured dashboards for all services as well as a "home" dashboard with selected metrics from all services are shipped and provisioned to the Grafana container.

More details at the monitoring page.

Migrating from Mailserver 1.1.3 or lower to to Mailserver 1.2.0 or higher

Some start-up / service unit enhancements were introduced in 1.2.0. This is a breaking change; upgrading required manual porting of existing customisations. If you're upgrading please read on.

Core mailserver

Mailserver service start-up script wrapper (start_mailserver.sh) has been moved to systemd/. Customisations to start-up in ./start_mailserver.sh must be ported to systemd/start_mailserver.sh.

Consequently, the service file in systemd/mailserver.service has been updated with the new path of the start-up wrapper script.

  • Either, the new service file must be copied from systemd/mailserver.service to /etc/systemd/system/ (and customisations in the existing /etc/systemd/system/mailserver.service - like e.g. custom HTTP / HTTPS ports - must be ported to the new unit file).
  • Or, the existing /etc/systemd/system/mailserver.service must be updated to point to the new start-up script.

Monitoring

Mailserver 1.2.0 ships monitoring services (grafana, promentheus, and pughgateway) as separate systemd services instead of spawning background jobs from a single start-up script.

If monitoring is enabled, all respective mailserver-monitoring* service files in systemd/ must be installed and enabled. Existing customisations in start_monitoring.sh must be ported to the respective service startup wrapper in systemd/mailserver-monitoring*.sh.

# Check script wrappers systemd/mailserver-monitoring*.sh and port customisations from start_monitoring.sh; then
systemctl stop mailserver-monitoring

cp systemd/mailserver-monitoring*.service /etc/systemd/system/

systemctl daemon-reload
systemctl enable mailserver-monitoring-grafana.service mailserver-monitoring-network.service mailserver-monitoring-prometheus.service mailserver-monitoring-pushgw.service mailserver-monitoring.service

systemctl start mailserver-monitoring

Issues and Workarounds

Integrating with other services

The mailserver can easily be extended with other services. Recipes for often desired services are collected in the contrib folder. While these aren't as automated as the core mailserver, the recipes aim to make the set-up of additional services as easy as possible.

Currently, this includes:

Contributing

Check out the repository layout to get started. If you'd like to work on a feature please state so in the corresponding feature issue. Please create a new issue if none exists for the feature you're aiming to implement.

Build the container

A Dockerfile is provided with this repo. (Re-)Build the container by issuing

$ docker build -t myemailserver .

Then update start_mailserver.sh and replace ghcr.io/t-lo/mailserver with myemailserver (or any other tag you've used in the docker build command above). Start your build:

./start_mailserver.sh
Clone this wiki locally