Skip to content

# Usage

This pages 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 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.

On the host, you should have a suitable container runtime (like Docker or Podman) installed. We assume Docker Compose is installed.

Podman Support

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

1. set an `MX` record for your domain `example.com` - in our example, the MX record contains `mail.example.com`
2. set an `A` record that resolves the name of your mail server - in our example, the A record contains `11.22.33.44`
3. (in a best-case scenario) set a `PTR` record that resolves the IP of your mail server - in our example, the PTR contains `mail.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:

- 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 `mail.example.com`. This does not imply your e-mails will look like `test@mail.example.com`, 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 `test@some-other-domain.com`, if the MX record for `some-other-domain.com` points to `mail.example.com`.
- The A record tells everyone which IP address the DNS name `mail.example.com` resolves to.
- The PTR record is the counterpart of the A record, telling everyone what name the IP address `11.22.33.44` resolves to.

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

    $ dig @1.1.1.1 +short MX example.com
    mail.example.com
    $ dig @1.1.1.1 +short A mail.example.com
    11.22.33.44
    $ dig @1.1.1.1 +short -x 11.22.33.44
    mail.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.

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:

    DMS_GITHUB_URL="https://github.com/docker-mailserver/docker-mailserver/blob/latest"
    wget "${DMS_GITHUB_URL}/docker-compose.yml"
    wget "${DMS_GITHUB_URL}/mailserver.env"

### Configuration Steps

1. First edit `docker-compose.yml` to your liking
   - Substitute `mail.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 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 `setup.sh` 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 `setup.sh`, here's some information about it.

If no DMS container is running, any `./setup.sh` 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:

    $ ./setup.sh help
    Image 'docker.io/mailserver/docker-mailserver:latest' not found. Pulling ...
    SETUP(1)

    NAME
        setup - 'docker-mailserver' Administration & Configuration script
    ...

    $ docker run --rm ghcr.io/docker-mailserver/docker-mailserver:latest setup help
    SETUP(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 running `docker 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 to our documentation about TLS.

### Aliases

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 postmaster@example.com user@example.com

### DKIM Keys

You can (and you should) generate DKIM keys. For more information:

- DKIM with OpenDKIM (enabled by default)
- DKIM with Rspamd (when using `ENABLE_RSPAMD=1`)

When keys are generated, you can configure your DNS server by just pasting the content of `config/opendkim/keys/domain.tld/mail.txt` to set up DKIM. See the documentation for more details.

Note

In case you're using LDAP, the setup looks a bit different as you do not add user accounts directly. Postfix doesn't know your domain(s) and you need to provide it when configuring DKIM:

    docker exec -ti <CONTAINER NAME> setup config dkim domain '<domain.tld>[,<domain2.tld>]'

### Advanced DNS Setup

You will very likely want to configure your DNS with these TXT records: SPF, DKIM, and DMARC.

The following illustrates what a (rather strict) set of records could look like:

    $ dig @1.1.1.1 +short TXT example.com
    "v=spf1 mx -all"
    $ dig @1.1.1.1 +short TXT dkim-rsa._domainkey.example.com
    "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQ..."
    $ dig @1.1.1.1 +short TXT _dmarc.example.com
    "v=DMARC1; p=reject; sp=reject; pct=100; adkim=s; aspf=s; fo=1"

### Custom User Changes & Patches

If you'd like to change, patch or alter files or behavior of `docker-mailserver`, you can use a script. See this 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