Skip to content


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 location docker-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 the necessary ports for mail
  3. You should be able to set a PTR 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.

About the Container Runtime

On the host, you need to have a suitable container runtime (like Docker or Podman) installed. We assume Docker Compose is installed. We have aligned file names and configuration conventions with the latest Docker Compose (currently V2) specification.

If you're using podman, make sure to read the related documentation.

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 bought and you want to be able to send and receive e-mails for the address On the most basic level, you will need to

  1. set an MX record for your domain - in our example, the MX record contains
  2. set an A record that resolves the name of your mail server - in our example, the A record contains
  3. (in a best-case scenario) set a PTR record that resolves the IP of your mail server - in our example, the PTR contains

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:

  • The MX 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 on This does not imply your e-mails will look like, the DNS name of your mail server is decoupled of the domain it serves e-mails for. In theory, you mail server could even serve e-mails for, if the MX record for points to
  • The A record tells everyone which IP address the DNS name resolves to.
  • The PTR record is the counterpart of the A record, telling everyone what name the IP address resolves to.

About The Mail Server's Fully Qualified Domain Name

The mail server's fully qualified domain name (FQDN) in our example above is Please note though that this is more of a convention, and not due to technical restrictions. One could also run the mail server

  1. on you would just need to change your MX record;
  2. on directly: you would need to change your MX record and probably read our docs on bare domain setups, as these setups are called "bare domain" setups.

The FQDN is what is relevant for TLS certificates, it has no (inherent/technical) relation to the email addresses and accounts DMS manages. That is to say: even though DMS runs on, or, or, there is nothing that prevents it from managing mail for - will just need to set its MX record to (or or

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

$ dig @ +short MX
$ dig @ +short A
$ dig @ +short -x

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 (
  2. GitHub Container Registry (

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

Event Image Tags
push on master edge
push a tag (v1.2.3) 1.2.3, 1.2, 1, latest

Get All Files

Issue the following commands to acquire the necessary files:

wget "${DMS_GITHUB_URL}/compose.yaml"
wget "${DMS_GITHUB_URL}/mailserver.env"

Configuration Steps

  1. First edit compose.yaml to your liking
    • Substitute 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 editing mailserver.env, but keep in mind that:
    • only basic VAR=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

Using the Correct Commands For Stopping and Starting DMS

Use docker compose up / down, not docker compose start / stop. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state.

Using Ctrl+C is not supported either!

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

Usage of when no DMS Container Is Running

We encourage you to directly use setup inside the container (like shown above). If you still want to use, here's some information about it.

If no DMS container is running, any ./ command will check online for the :latest image tag (the current stable release), performing a docker pull ... if necessary followed by running the command in a temporary container:

$ ./ help
Image '' not found. Pulling ...

    setup - 'docker-mailserver' Administration & Configuration script

$ docker run --rm setup help

    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 running docker exec -ti <CONTAINER NAME> setup email add That's it! It really is that easy.

Further Miscellaneous Steps

Setting up TLS

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


You should add at least one alias, the postmaster alias. This is a common convention, but not strictly required.

docker exec -ti <CONTAINER NAME> setup alias add

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 a dedicated 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. See this part of our documentation for a detailed explanation.


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

  1. MX Toolbox
  2. DMARC Analyzer