Usage

This page explains how to get started with DMS. The guide uses Docker Compose as a reference. In our examples, a volume mounts the host locationdocker-data/dms/config/ to/tmp/docker-mailserver/ inside the container.

Preliminary Steps

Before you can get started with deploying your own mail server, there are some requirements to be met:

1. You need to have a host that you can manage.
2. You need to own a domain, and you need to be able to manage DNS for this domain.

Host Setup

There are a few requirements for a suitable host system:

1. The host should have a static IP address; otherwise you will need to dynamically update DNS (undesirable due to DNS caching)
2. The host should be able to send/receive on thenecessary ports for mail
3. You should be able to set aPTR record for your host; security-hardened mail servers might otherwise reject your mail server as the IP address of your host does not resolve correctly/at all to the DNS name of your server.

Minimal DNS Setup

The DNS setup is a big and essential part of the whole setup. There is a lot of confusion for newcomers and people starting out when setting up DNS. This section provides an example configuration and supplementary explanation. We expect you to be at least a bit familiar with DNS, what it does and what the individual record types are.

Now let's say you just boughtexample.com and you want to be able to send and receive e-mails for the addresstest@example.com. On the most basic level, you will need to

1. set anMX record for your domainexample.com - in our example, the MX record containsmail.example.com
2. set anA record that resolves the name of your mail server - in our example, the A record contains11.22.33.44
3. (in a best-case scenario) set aPTR record that resolves the IP of your mail server - in our example, the PTR containsmail.example.com

We will later dig into DKIM, DMARC & SPF, but for now, these are the records that suffice in getting you up and running. Here is a short explanation of what the records do:

• TheMX record tells everyone which (DNS) name is responsible for e-mails on your domain. Because you want to keep the option of running another service on the domain name itself, you run your mail server onmail.example.com. This does not imply your e-mails will look liketest@mail.example.com, the DNS name of your mail server is decoupled of the domain it serves e-mails for. Your mail server could also handle emails fortest@some-other-domain.com, if the MX record forsome-other-domain.com points tomail.example.com.
• TheA record tells everyone which IP address the DNS namemail.example.com resolves to.
• ThePTR record is the counterpart of the A record, telling everyone what name the IP address11.22.33.44 resolves to.

If you setup everything, it should roughly look like this:

$dig@1.1.1.1+shortMXexample.commail.example.com$dig@1.1.1.1+shortAmail.example.com11.22.33.44$dig@1.1.1.1+short-x11.22.33.44mail.example.com

Deploying the Actual Image

Tagging Convention

To understand which tags you should use, read this section carefully.Our CI will automatically build, test and push new images to the following container registries:

1. DockerHub (docker.io/mailserver/docker-mailserver)
2. GitHub Container Registry (ghcr.io/docker-mailserver/docker-mailserver)

All workflows are using the tagging convention listed below. It is subsequently applied to all images.

Get All Files

Issue the following commands to acquire the necessary files:

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

Configuration Steps

1. First editcompose.yaml to your liking
   • Substitutemail.example.com according to your FQDN.
   • If you want to use SELinux for the./docker-data/dms/config/:/tmp/docker-mailserver/ mount, append-z or-Z.
2. Then configure the environment specific to the mail server by editingmailserver.env, but keep in mind that:
   • onlybasicVAR=VAL is supported
   • do not quote your values
   • variable substitution is not supported, e.g.OVERRIDE_HOSTNAME=$HOSTNAME.$DOMAINNAME does not work

Get Up and Running

For an overview of commands to manage DMS config, run:docker exec -it <CONTAINER NAME> setup help.

$./setup.shhelpImage 'ghcr.io/docker-mailserver/docker-mailserver:latest' not found. Pulling ...SETUP(1)NAME    setup - 'docker-mailserver' Administration & Configuration script...$dockerrun--rmghcr.io/docker-mailserver/docker-mailserver:latestsetuphelpSETUP(1)NAME    setup - 'docker-mailserver' Administration & Configuration script...

On first start, you will need to add at least one email account (unless you're using LDAP). You have two minutes to do so, otherwise DMS will shutdown and restart. You can add accounts by runningdocker exec -ti <CONTAINER NAME> setup email add user@example.com.That's it! It really is that easy.

Further Miscellaneous Steps

Setting up TLS

You definitely want to setup TLS. Please refer toour documentation about TLS.

Aliases

You should add at least onealias, thepostmaster alias. This is a common convention, but not strictly required.

dockerexec-ti<CONTAINERNAME>setupaliasaddpostmaster@example.comuser@example.com

Advanced DNS Setup - DKIM, DMARC & SPF

You will very likely want to configure your DNS with these TXT records:SPF, DKIM, and DMARC. We also ship adedicated page in our documentation about the setup of DKIM, DMARC & SPF.

Custom User Changes & Patches

If you'd like to change, patch or alter files or behavior of DMS, you can use a script. Seethis part of our documentation for a detailed explanation.

Testing

Here are some tools you can use to verify your configuration:

1. MX Toolbox
2. DMARC Analyzer
3. mail-tester.com
4. multiRBL.valli.org
5. internet.nl