How to Deploy docker-mailserver on a VPS

copysudo ufw allow 25/tcp
sudo ufw allow 143/tcp
sudo ufw allow 465/tcp
sudo ufw allow 587/tcp
sudo ufw allow 993/tcp
sudo ufw status verbose

#Install docker-mailserver

DMS ships an official compose.yaml and mailserver.env — fetch both rather than hand-writing them, since the project keeps them current with the image:

copymkdir -p ~/mailserver && cd ~/mailserver

copyDMS_URL="https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master"
wget "${DMS_URL}/compose.yaml"
wget "${DMS_URL}/mailserver.env"

The compose file's only required edit is the mail server's hostname — it ships as the placeholder mail.example.com. For a real deployment, edit that value in compose.yaml to your own FQDN by hand (say mail.example.com, with your DNS MX record pointing at it). For this install we don't have a real domain yet, so we derive a working one from the box's own public IP using sslip.io — a DNS service that resolves any <anything>.<ip>.sslip.io name straight to <ip> — and set it non-interactively:

copyexport SERVER_IP="$(curl -s https://ifconfig.me)"
export MAIL_DOMAIN="mail.${SERVER_IP}.sslip.io"
sed -i "s/mail.example.com/${MAIL_DOMAIN}/" compose.yaml
grep "hostname:" compose.yaml

Bring the stack up:

copydocker compose up -d
docker compose logs --tail 40 mailserver

You have a two-minute window. On first boot, DMS waits for at least one mailbox to be added — if none shows up within two minutes, it assumes something's wrong, shuts down, and restarts to try again. That's not a bug to work around; it's why the very next step happens immediately, before you go read documentation or grab coffee.

#Create your first mailbox, then enable DKIM

Add a mailbox with setup email add. Normally it prompts interactively for a password (so the password never lands in your shell history) — but it also accepts the password as a second argument, which is what makes this scriptable:

copysleep 10
export MAIL_USER="postmaster@${MAIL_DOMAIN}"
export MAIL_PASSWORD="$(openssl rand -base64 24)"
docker exec -i mailserver setup email add "${MAIL_USER}" "${MAIL_PASSWORD}"

postmaster@ is a deliberate choice, not just a placeholder — RFC 5321 requires every mail domain to have a working postmaster mailbox, and mailserver.env's POSTMASTER_ADDRESS defaults to exactly this address for bounce and report delivery. For a real domain you'll add your actual mailboxes the same way (setup email add you@example.com, letting it prompt for a password interactively so it never touches shell history), and postmaster@ is one you'll want to exist regardless.

Confirm it landed, then generate DKIM keys — setup config dkim runs non-interactively with sane defaults (2048-bit key, mail selector, the domain(s) already known to DMS from the mailbox you just added):

copydocker exec -i mailserver setup email list
docker exec -i mailserver setup config dkim

The generated public key — the value you'll publish as a DNS TXT record — is written to the config volume on the host:

copycat "docker-data/dms/config/opendkim/keys/${MAIL_DOMAIN}/mail.txt"

Give the container a moment, then confirm it's reported healthy — the image ships its own internal healthcheck, which docker compose ps surfaces:

copysleep 20
docker compose ps

That's the entire install: a running container, a mailbox, and a DKIM keypair. Everything from here is either backup hygiene or the DNS work that turns "a mail server exists" into "mail actually arrives."

#DNS & deliverability — read this before you send real mail

This is the part the verified install-and-boot check above does not, and cannot, cover. MX, SPF, DKIM, DMARC, PTR, and an unblocked port 25 all require a real domain and a server with a bit of sending history — none of which a fresh VPS on a throwaway sslip.io hostname has. Treat this section as your go-live checklist, not something this guide can verify for you:

• MX record. Point your domain's MX record at your mail server's FQDN (mail.example.com), not at the bare domain and not at an IP.
• SPF (TXT record on the bare domain). Publish v=spf1 mx ~all (or -a if you want a hard fail) so receiving servers know your mail server is authorized to send for your domain.
• DKIM (TXT record). Publish the key generated above as a TXT record at mail._domainkey.<your-domain> — the file you cat-ed contains the exact record, pre-formatted for a DNS zone file.
• DMARC (TXT record at _dmarc.<your-domain>). Start permissive while you confirm SPF/DKIM are passing — v=DMARC1; p=none; rua=mailto:postmaster@<your-domain> — then tighten to p=quarantine or p=reject once reports look clean.
• PTR (reverse DNS). Your VPS provider — Hetzner, Kamatera, DigitalOcean, all of them — sets this from their control panel or support desk, not from DNS you manage. It must resolve your IP back to your mail hostname exactly, or major providers will bounce or spam-bin your mail outright.
• Port 25 outbound. Most VPS providers block it by default, precisely because unblocked port 25 on cheap, disposable VPS instances is a top spam vector. Check your provider's policy and file an unblock request (often tied to identity verification) before you assume delivery is broken — it might just be a blocked port.

None of this is optional for real mail, and none of it is fast — DNS propagation and IP-reputation warm-up both take time. Budget days, not minutes, between "server is up" and "mail reliably lands in Gmail's inbox."

#Backups

Three things live in ~/mailserver/docker-data/dms/, and all three matter:

• mail-data/ — the actual mailboxes: every message, every folder.
• mail-state/ — Postfix/Dovecot working state (indices, queues).
• config/ — mailbox definitions, aliases, and critically, the DKIM private keys. Lose this without a backup and you'll regenerate DKIM keys from scratch, which means re-publishing DNS and losing signing continuity — annoying, not catastrophic, but avoidable.

copycd ~/mailserver
tar czf "mailserver-backup-$(date +%F).tar.gz" \
  docker-data/dms/mail-data docker-data/dms/mail-state docker-data/dms/config

Ship that archive off the box on a schedule — a server that dies with its only backup sitting next to it hasn't been backed up. Test a restore into a throwaway instance now and then; an archive you've never restored is a guess.

#Upgrades

copycd ~/mailserver
docker compose pull
docker compose up -d

Pull the newer image and recreate the container against your unchanged volumes — mailboxes, keys, and config all survive. Read the release notes before a major version bump; mail software is conservative but not immune to occasional config-format changes.

#Troubleshooting

Mail sends fine internally but never reaches Gmail/Outlook. This is almost always the deliverability checklist above, not a DMS bug. Check SPF, DKIM, and DMARC are all passing with a tool like mail-tester.com, confirm your PTR record matches your hostname, and confirm port 25 isn't blocked outbound by your provider.

Container restarts in a loop shortly after docker compose up -d. You likely missed the two-minute mailbox window. Check docker compose logs --tail 100 mailserver for the shutdown reason, then re-run docker compose up -d followed immediately by setup email add.

setup email add or setup config dkim hangs or errors with "no such container." The container isn't up yet, or the name doesn't match. Confirm with docker compose ps — the service is named mailserver in the official compose file — and give it a few more seconds after up -d before running setup commands.

DKIM TXT record doesn't match what receivers see. DNS providers sometimes split long TXT records into quoted segments automatically; if you're pasting the generated record by hand, use your provider's TXT record field as-is rather than reformatting it — most parse the OpenDKIM output's line breaks correctly, but paste the whole block if unsure.

copydocker compose logs -f mailserver

#Verification + next steps

What this guide verifies: the container installs, boots, reports healthy, accepts a mailbox via setup email add, and generates a DKIM keypair via setup config dkim — all on a fresh Ubuntu 26.04 VPS. That's the verified stamp's actual scope.

What it deliberately does not verify: that mail sent from this server lands in anyone's inbox. Real deliverability depends on DNS records, PTR setup, and port 25 access this guide can only document, not test from a throwaway box. Work through the DNS & deliverability checklist above with your real domain, then send a test message to a checker like mail-tester.com before you trust this server with real mail.

From there, it's routine maintenance: back up config/ and mail-data/ on a schedule, keep the image current, and watch your sending reputation the way you'd watch any production service. A Hetzner CX22 comfortably covers the default (ClamAV-off) footprint; size up to Kamatera's larger tiers if you turn ClamAV on. See Best VPS for self-hosting for the ranked picks.