docker-mailserver on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of docker-mailserver on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. docker-mailserver (DMS) is a production ready, full stack mail server: a Postfix MTA for sending and receiving, Dovecot for IMAP mailbox access, Rspamd for spam scoring, DKIM signing and verification, SPF and DMARC, and Fail2ban for brute force protection, all configured through a single environment file and a plain file based account store. There is no database to run and no web console to secure.

The cloudimg image ships the free and open source, MIT licensed docker-mailserver, run the officially supported way as the upstream container pinned by image digest, on the five standard mail ports. Mail storage lives on a dedicated, independently resizable Azure data disk. Nothing ships with a known credential: the image contains no mailbox at all, and a unique postmaster password and a unique self signed TLS certificate are generated on each VM at first boot, before the server is reachable. Backed by 24/7 cloudimg support.

docker-mailserver is a trademark of its respective owner. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by The Docker Mailserver Organization. It ships the free and open source MIT licensed self hosted software, unmodified.

Before you start: Azure blocks outbound port 25

This is the single most important thing to know before you deploy a mail server on Azure, so it is stated first rather than buried.

Microsoft blocks outbound TCP port 25 from Azure virtual machines. Per Microsoft's current guidance:

• Enterprise Agreement (EA) and Microsoft Customer Agreement for enterprise (MCA-E) subscriptions are not blocked.
• Enterprise Dev/Test subscriptions are blocked by default but can be exempted through the virtual network's Diagnose and solve problems → Cannot send email (SMTP-Port 25) self service flow. VMs must then be stopped, deallocated and restarted.
• All other subscription types — pay as you go, MSDN, CSP, Free Trial, Azure Pass, Azure in Open and Education — are blocked with no exemption available. Requests to lift the block are not granted.

What this means in practice for this image:

	Works on every Azure subscription
Receiving mail on port 25 from other mail servers	Yes — inbound is completely unaffected
IMAP mailbox access on 143 and 993	Yes
Authenticated submission from your mail clients on 587 and 465	Yes
Sending by connecting directly to recipient MX servers on port 25	Only on EA / MCA-E
Sending through an authenticated smarthost relay on port 587	Yes — Microsoft's own recommendation

So as shipped this is a fully functional receiving and IMAP mail server on any subscription, and for sending you configure a relay. This is not a limitation of docker-mailserver or of this image — it is an Azure platform policy that applies to every VM based mail server. The image is configured relay first for exactly this reason, and RELAY_PORT defaults to 587 rather than upstream's default of 25, which would silently time out.

The screenshot below is this measurement taken on a real Azure VM, not a claim from documentation:

What is included:

• docker-mailserver 15.1.0 (the MIT licensed full stack mail server), pinned by image digest
• Postfix 3.7.11 (MTA), Dovecot 2.3.19.1 (IMAP), Rspamd 3.12.1 (spam, DKIM, SPF, DMARC) and Fail2ban 1.1.0
• The five standard mail ports published: 25 SMTP, 143 IMAP4 STARTTLS, 465 ESMTP implicit TLS, 587 ESMTP STARTTLS, 993 IMAP4 implicit TLS
• Fail2ban enabled with the NET_ADMIN capability so bans are actually enforced, guarding the internet facing ports
• A dedicated 64 GiB ext4 Azure data disk at /var/lib/docker-mailserver holding the Maildir, mail state, mail logs and configuration, independently resizable
• A unique self signed TLS certificate and a unique postmaster mailbox password generated per VM on first boot, never baked into the image
• No mailbox and no credential in the shipped image at all
• ClamAV present but disabled by default, enabled with a single command when you have the RAM for it
• Bundled component licence notices and a GPL v2 written offer for source, shipped in the image
• docker-mailserver.service and docker-mailserver-firstboot.service as systemd units, enabled and active on boot
• Ubuntu 24.04 LTS base with latest security patches applied at build time
• Azure Linux Agent for seamless cloud integration and SSH key injection

Prerequisites

• Active Azure subscription, SSH public key, VNet + subnet in target region
• Subscription to the docker-mailserver listing on Azure Marketplace
• A domain name you control, with access to its DNS records
• An authenticated SMTP relay account if you need to send mail (see the sending section)

Recommended virtual machine size: Standard_B2ms (2 vCPU, 8 GB RAM). The shipped stack (Postfix, Dovecot, Rspamd with its Redis, Fail2ban) runs in roughly 1 to 1.5 GB, so Standard_B2s (2 vCPU, 4 GB) is workable for evaluation. 8 GB is recommended because it leaves genuine headroom for mailbox volume and for enabling ClamAV, which upstream documents as needing around 3 GB on its own. For high mail volume use Standard_D2s_v3 or larger.

NSG inbound rules. Allow 22/tcp from your management network only. The mail ports must be reachable from the networks that use them:

Port	Purpose	Who needs it
25/tcp	SMTP — inbound mail from other mail servers	The internet, if you receive mail from outside
587/tcp	Submission, STARTTLS	Your users' mail clients
465/tcp	Submission, implicit TLS	Your users' mail clients
143/tcp	IMAP4, STARTTLS	Your users' mail clients
993/tcp	IMAP4, implicit TLS	Your users' mail clients

Port 25 is the only one that genuinely needs to be open to the whole internet, and only if you want to receive mail from arbitrary senders. If this server is only for sending through a relay and reading over IMAP, leave 25 closed to the internet.

Deploying from the Azure Marketplace

az vm create \
  --resource-group my-mail-rg \
  --name my-mailserver \
  --image cloudimg:docker-mailserver-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard \
  --location eastus

Then open the mail ports on the network security group:

az network nsg rule create -g my-mail-rg --nsg-name my-mailserverNSG --name allow-smtp \
  --priority 1001 --destination-port-ranges 25 --access Allow --protocol Tcp
az network nsg rule create -g my-mail-rg --nsg-name my-mailserverNSG --name allow-submission \
  --priority 1002 --destination-port-ranges 587 465 --access Allow --protocol Tcp \
  --source-address-prefixes "<your-mgmt-cidr>"
az network nsg rule create -g my-mail-rg --nsg-name my-mailserverNSG --name allow-imap \
  --priority 1003 --destination-port-ranges 993 143 --access Allow --protocol Tcp \
  --source-address-prefixes "<your-mgmt-cidr>"

First boot

On the first boot of each VM, docker-mailserver-firstboot.service derives this VM's mail hostname, generates a TLS certificate for it, generates a random postmaster password, starts the mail server and records everything in a root only file. It runs once and takes about 30 seconds.

Check that the services are up:

systemctl is-active docker.service docker-mailserver.service

Expected output:

active
active

Confirm the container is running and pinned by digest:

sudo docker ps --format '{{.Names}}  {{.Image}}  {{.Status}}'
cat /opt/docker-mailserver/IMAGE-DIGEST.txt

The digest recorded there is the exact image this VM runs:

ghcr.io/docker-mailserver/docker-mailserver@sha256:af51b15dd3fc72153c0e90eb7692bb5e3a463212d87959a80fa7aa89b617d44a

Confirm all five mail ports are listening:

ss -lntH '( sport = :25 or sport = :143 or sport = :465 or sport = :587 or sport = :993 )' | awk '{print $4}' | sort -u

Per VM credentials

Everything unique to this VM is written to /root/docker-mailserver-credentials.txt, mode 0600, owned by root:

sudo cat /root/docker-mailserver-credentials.txt

About the one mailbox. docker-mailserver will not start Dovecot with zero accounts — it warns and shuts the container down after 120 seconds. So exactly one mailbox is created at first boot: the postmaster@ address, which every mail server is required by RFC 5321 to accept anyway. Its password is generated randomly on your VM, at first boot, and is not present in the image, in any configuration file, or known to cloudimg. The shipped image contains no mailbox at all; first boot asserts this and refuses to proceed if it finds one.

Change the postmaster password whenever you like:

sudo docker exec -ti mailserver setup email update postmaster@<your-domain>

Verifying the server actually works

The image ships a self test that proves real mail flow end to end rather than just checking that a port is open. It creates nothing and leaves nothing behind:

sudo /usr/local/sbin/dms-selftest.sh

It submits a message on port 587 with STARTTLS and SMTP authentication, polls IMAP on 993 until the message is genuinely delivered, fetches it and asserts the exact content, then removes it. It also runs three negative controls that must each be refused: an unauthenticated relay attempt to an external domain on port 25, a submission with a wrong password, and an IMAP login with a wrong password.

The open relay check is the important one. An open relay is a mail server that will forward mail to arbitrary external domains for anyone who asks, and running one gets your IP address blacklisted within hours and makes you a spam source. This image is not an open relay: PERMIT_DOCKER=none means only the container's own loopback is a trusted network, so anything arriving from outside must authenticate before it can relay. You can confirm this yourself from another machine:

printf 'EHLO probe\r\nMAIL FROM:<probe@example.net>\r\nRCPT TO:<victim@example.org>\r\nQUIT\r\n' | nc <vm-ip> 25

The RCPT TO must be refused with 554 5.7.1 <victim@example.org>: Relay access denied. If it is ever accepted, stop and investigate before putting the server into service.

Setting your own domain

The default mail hostname is derived from the VM's own name and is only useful for testing. Point a DNS A record at the VM, then set the real hostname. This regenerates the TLS certificate for the new name and restarts the server:

sudo /usr/local/sbin/dms-set-domain.sh mail.<your-domain>

Then create your mailboxes. Omit the password argument to be prompted for it rather than putting it in your shell history:

sudo docker exec -ti mailserver setup email add you@<your-domain>
sudo docker exec mailserver setup email list

DNS records

For mail to work reliably you need these records on <your-domain>:

Type	Name	Value	Purpose
A	mail	your VM's public IP	Resolves the mail host
MX	@	10 mail.<your-domain>.	Tells other servers where to deliver
TXT	@	v=spf1 mx ~all	SPF: authorises this host to send
TXT	_dmarc	v=DMARC1; p=quarantine; rua=mailto:postmaster@<your-domain>	DMARC policy
PTR	(reverse of your IP)	mail.<your-domain>.	Reverse DNS — set on the Azure public IP resource

Generate a DKIM key and publish it:

sudo docker exec mailserver setup config dkim
sudo cat /var/lib/docker-mailserver/config/rspamd/dkim/*.public.dns.txt

Publish the contents as a TXT record at the name shown in that file.

Reverse DNS matters more than people expect. Many large providers reject mail from hosts with no PTR record or a PTR that does not match the sending hostname. Set it on the Azure public IP resource:

az network public-ip update --resource-group my-mail-rg --name my-mailserverPublicIP --reverse-fqdn mail.<your-domain>

Note that if you send through a relay (the normal case on Azure) the relay's reputation and DNS records are what recipients see, so this matters most on EA / MCA-E subscriptions delivering directly.

Sending mail: the authenticated relay

Because Azure blocks outbound port 25 on most subscriptions, configure an authenticated smarthost. This is Microsoft's own recommendation and works on every subscription type. Use any provider that offers authenticated SMTP on port 587 — Azure Communication Services, SendGrid, Mailgun, Amazon SES, Postmark, or your organisation's own relay:

# Example with SendGrid: the user is literally "apikey" and the password is the API key.
sudo /usr/local/sbin/dms-set-relay.sh smtp.sendgrid.net 587 apikey <your-token>

The script writes DEFAULT_RELAY_HOST, RELAY_HOST, RELAY_PORT, RELAY_USER and RELAY_PASSWORD into /opt/docker-mailserver/mailserver.env (mode 0600) and restarts the server. It warns you if you pass port 25, since that will time out on most Azure subscriptions.

Confirm Postfix picked it up:

sudo docker exec mailserver postconf relayhost

Then send a real message through your relay and watch it leave:

sudo docker exec mailserver tail -f /var/log/mail/mail.log

A successful relayed delivery logs status=sent with your relay host in the relay= field. If you see status=deferred with Connection timed out to port 25, you are still trying to deliver directly and the relay is not configured.

Check whether your subscription is blocked. Measure it rather than guessing:

timeout 12 bash -c 'exec 3<>/dev/tcp/alt1.aspmx.l.google.com/25' && echo "port 25 REACHABLE (EA/MCA-E)" || echo "port 25 BLOCKED - use a relay"
timeout 12 bash -c 'exec 3<>/dev/tcp/smtp.sendgrid.net/587' && echo "port 587 REACHABLE" || echo "port 587 blocked"

Connecting a mail client

Setting	Value
Incoming (IMAP) server	mail.<your-domain>, port 993, SSL/TLS
Outgoing (SMTP) server	mail.<your-domain>, port 587, STARTTLS
Username	the full email address, e.g. you@<your-domain>
Password	the password you set with setup email add
Authentication	normal password

Until you install a real certificate your client will warn about the self signed certificate. That is expected — the connection is still encrypted, but the identity is not verified by a public authority.

Installing a real TLS certificate

Use any ACME client on the host to obtain a certificate for mail.<your-domain>, then point the mail server at it. With certbot in standalone mode (port 80 must be reachable and free):

sudo apt-get install -y certbot
sudo certbot certonly --standalone -d mail.<your-domain>
sudo cp /etc/letsencrypt/live/mail.<your-domain>/fullchain.pem /var/lib/docker-mailserver/config/ssl/cert.pem
sudo cp /etc/letsencrypt/live/mail.<your-domain>/privkey.pem /var/lib/docker-mailserver/config/ssl/key.pem
sudo systemctl restart docker-mailserver.service

The paths cert.pem and key.pem in the config volume are what SSL_TYPE=manual points at, so no configuration change is needed — replace the files and restart. Add the same copy commands to a certbot renewal hook so renewals take effect.

Spam filtering and DKIM

This image runs Rspamd rather than upstream's default Amavis and SpamAssassin combination. Rspamd handles spam scoring, DKIM signing and verification, SPF and DMARC in a single daemon, replacing five separate services. That is materially less memory for the same function, and it is upstream's own documented modern stack.

Check that it is scanning:

sudo docker exec mailserver rspamc stat
sudo docker exec mailserver tail -5 /var/log/mail/rspamd.log

Messages scanned climbing above zero is the proof that Rspamd is actually in the mail path, rather than merely running.

Spam is delivered to the recipient's Junk folder rather than rejected outright, so nothing is silently lost while you tune. Moving a message into or out of Junk trains the Bayesian classifier, because RSPAMD_LEARN=1 is set.

Brute force protection

The mail ports are internet facing, so Fail2ban is enabled with the NET_ADMIN capability the container needs to actually install bans. On a VM with a public IP you will typically see real brute force attempts within minutes of first boot.

sudo docker exec mailserver setup fail2ban status

Unban an address if you lock yourself out:

sudo docker exec mailserver setup fail2ban unban 203.0.113.10

Backing up mail

All mail state is on the dedicated data disk at /var/lib/docker-mailserver:

findmnt -no SOURCE,TARGET,FSTYPE,SIZE /var/lib/docker-mailserver
sudo du -sh /var/lib/docker-mailserver/mail-data

Path	Contents
mail-data/	The Maildir tree — every message
config/	Accounts, aliases, DKIM keys, TLS material
mail-state/	Runtime state, Rspamd's Bayes database
mail-logs/	Mail logs

Because it is a separate Azure managed disk you can snapshot it independently of the OS disk, and resize it without rebuilding the VM. Snapshot it on a schedule; config/ in particular holds your DKIM private keys, which cannot be regenerated without republishing DNS.

Licences and source code

docker-mailserver itself is MIT licensed. The container bundles third party components under a range of licences, including several under the GNU GPL v2. The upstream container image is built on debian:12-slim, which strips /usr/share/doc, so cloudimg recovers those copyright notices at build time and ships them in this image:

ls /opt/docker-mailserver/licenses/copyright/
cat /opt/docker-mailserver/licenses/copyright/fail2ban/copyright
head -20 /opt/docker-mailserver/licenses/common-licenses/GPL-2
wc -l /opt/docker-mailserver/licenses/PACKAGE-MANIFEST.txt

Component	Licence
docker-mailserver	MIT
Postfix	EPL-2.0 or IPL-1.0 (recipient's choice)
Dovecot	LGPL-2.1 core, MIT in parts
Rspamd	Apache-2.0
OpenDKIM / OpenDMARC	BSD-3-Clause, Sendmail Open Source Licence
Fail2ban	GPL-2.0-or-later
ClamAV	GPL-2.0-only
Amavis	GPL-2.0-or-later

The GPL v2 components carry a source availability obligation. GPL v2 section 3(c), which lets a distributor pass along the offer it received, applies only to non commercial distribution, and GPL v2 has no equivalent of GPL v3's "point at a third party server" option — so cloudimg makes its own written offer under section 3(b). It is shipped in the image:

cat /opt/docker-mailserver/THIRD-PARTY-LICENSES.md

The exact package versions the offer is pinned to are in /opt/docker-mailserver/licenses/PACKAGE-MANIFEST.txt. To request source, contact support@cloudimg.co.uk quoting the image digest and the component you need.

Troubleshooting

The container keeps restarting and the logs say "You need at least one mail account to start Dovecot". docker-mailserver requires at least one mailbox. First boot creates the postmaster account automatically; if you deleted every account, add one back with setup email add.

Mail sits in the queue with Connection timed out to port 25. This is the Azure outbound block. Configure a relay with dms-set-relay.sh as described above. Inspect the queue with:

sudo docker exec mailserver postqueue -p

Mail is delivered to recipients' spam folders. Check SPF, DKIM, DMARC and reverse DNS. Send a message to a mail tester service and review the report. If you relay, most of this is governed by the relay provider's configuration.

A mail client cannot authenticate. The username is the full email address, not the local part. Confirm the account exists with setup email list and check sudo docker exec mailserver tail -50 /var/log/mail/mail.log for the rejection reason.

Locked out by Fail2ban. Unban your address as shown above, from an SSH session.

Take a quick health snapshot:

systemctl is-active docker.service docker-mailserver.service
sudo docker ps --format '{{.Names}}  {{.Status}}'
sudo docker exec mailserver setup email list

For the full end to end proof (submission, delivery, IMAP retrieval and the open relay check) re-run sudo /usr/local/sbin/dms-selftest.sh from the verification section above.

Optional: enabling ClamAV antivirus

ClamAV is present in the image but disabled by default, which is also upstream's default. Upstream's own FAQ notes that ClamAV reads its entire signature database into RAM — around 850 MB and growing — and that without swap you may need 3 GB for it alone. Enabling it by default would put a small VM into out of memory failure on first boot, so it is opt in:

# Run this only after resizing the VM to Standard_B2ms (8 GB) or larger.
# The script refuses to run below 6 GB rather than let ClamAV exhaust memory.
sudo /usr/local/sbin/dms-enable-clamav.sh

The script refuses to run on a VM with less than 6 GB of RAM and tells you to resize first. That guard is deliberate and was set from measurement, not guesswork: on a 4 GB VM this build watched ClamAV's signature load push the machine into swap and stall the mail server. On the recommended Standard_B2ms (8 GB) there is ample headroom. The first signature refresh takes several minutes; watch it with sudo docker exec mailserver tail -f /var/log/mail/mail.log.

Support

cloudimg provides 24/7 support for this image. Contact support@cloudimg.co.uk.