docs: Explain how to configure maddy with multiple domains

Closes #198.

docs/tutorials/multiple-domains.md

@@ -0,0 +1,98 @@
+# Multiple domains configuration
+
+## Separate account namespaces
+
+Given two domains, example.org and example.com. foo@example.org and
+foo@example.com are different and completely independent accounts.
+
+All changes needed to make it work is to make sure all domains are specified in
+the `$(local_domains)` macro in the main configuration file. Note that you need
+to pick one domain as a "primary" for use in auto-generated messages.
+```
+$(primary_domain) = example.org
+$(local_domains) = $(primary_domain) example.com
+```
+
+The base configuration is done. You can create accounts using maddyctl using
+both domains in the name, send and receive messages and so on.  Do not forget
+to configure corresponding SPF, DMARC and MTA-STS records as was
+recommended in the [introduction tutorial](setting-up.md).
+
+### DKIM
+
+However, one thing needs special attention since at the moment maddy lacks the
+ability to automatically select the corresponding DKIM key. Without additional
+changes with the above configuration it will sign all messages using the key
+for the primary domain. So you should configure corresponding mappings to make
+it use the proper key depending on the sender domain.
+
+To do so, open your configuration and look for the `submission` endpoint block.
+Then take a look at `default_destination` directive that is responsible for
+handling deliveries to non-local addresses there.
+
+You will notice it referes to the `local_modifiers` block which uses `sign_dkim
+$(primary_domain) default`. It is kinda obvious what is happening here.
+
+First, remove the `deliver_to &remote_queue` line from here and replace it with
+the following:
+```
+reroute {
+  source example.com {
+    modify { sign_dkim example.com default }
+    deliver_to &remote_queue
+  }
+  source example.org {
+    modify { sign_dkim example.org default }
+    deliver_to &remote_queue
+  }
+  default_source {
+    reject 501 5.1.8 "Non-local sender domain"
+  }
+}
+```
+Replace example.com and example.org with your domains. Add more `source`
+blocks if you need to handle more domains.
+
+This whole block tells maddy to take a look at the sender domain after deciding
+that the message should be sent to the Internet and apply the corresponding set
+of modifiers. Each set of modifiers consequently contains the `sign_dkim`
+module reference that is responsible for DKIM signature creation using
+domain-specific key. After that the message ends up in the outbound queue as
+usual.
+
+## Single account namespace
+
+Lets say you want to handle messages for domains example.org and example.com
+and make that foo@example.org and foo@example.com are the same accounts.
+Sadly, this case is not very well-supported by maddy, but it still can be
+implemented.
+
+You already should have the primary domain set for autogenerated messages and
+so on. The idea is to redirect all messages from non-primary domains to the
+primary one.
+
+For each handled domain, the following line should be added to the
+`local_modifiers` block:
+```
+replace_rcpt /(.+)@example.com/ $1@$(primary_domain)
+```
+It does regexp replacement, turning anything@example.com into
+anything@$(primary_domain) where $(primary_domain) in our case is example.org.
+
+E.g.
+```
+$(primary_domain) = example.org
+
+modifiers local_modifiers {
+    replace_rcpt /(.+)@example.net/ $1@$(primary_domain)
+    replace_rcpt /(.+)@example.com/ $1@$(primary_domain)
+}
+```
+With that configuration, all messages for foo@example.net and foo@example.com
+will end up in the foo@example.org mailbox.
+
+Note, however, no account credentials aliasing is done. Users should always use
+the account name with the primary domain to access IMAP mailboxes.
+
+**Note 1**: All domains should still be listed in the `$(local_domains)` macro.
+**Note 2**: Section about DKIM key selection still applies.