From 1157868370d2767009fc587601fa71b0e2f7f7e9 Mon Sep 17 00:00:00 2001
From: Florent Daigniere <nextgens@freenetproject.org>
Date: Thu, 23 Sep 2021 16:08:52 +0200
Subject: [PATCH] Document how to setup autoconfig

---
 docs/faq.rst                            | 52 +++++++++++++++++++++++++
 towncrier/newsfragments/224.enhancement |  1 +
 2 files changed, 53 insertions(+)
 create mode 100644 towncrier/newsfragments/224.enhancement

diff --git a/docs/faq.rst b/docs/faq.rst
index 01557237..177e65d7 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -394,6 +394,58 @@ Mailu can serve an `MTA-STS policy`_; To configure it you will need to:
 .. _`1798`: https://github.com/Mailu/Mailu/issues/1798
 .. _`MTA-STS policy`: https://datatracker.ietf.org/doc/html/rfc8461
 
+How do I setup client autoconfiguration?
+````````````````````````````````````````
+
+Mailu can serve an `XML file for autoconfiguration`_; To configure it you will need to:
+
+1. add ``autoconfig.example.com`` to the ``HOSTNAMES`` configuration variable (and ensure that a valid SSL certificate is available for it; this may mean restarting your smtp container)
+
+2. configure an override with the policy itself; for example, your ``overrides/nginx/autoconfiguration.conf`` could read:
+
+.. code-block:: bash
+
+   location ^~ /mail/config-v1.1.xml {
+   return 200 "<?xml version=\"1.0\"?>
+   <clientConfig version=\"1.1\">
+   <emailProvider id=\"%EMAILDOMAIN%\">
+   <domain>%EMAILDOMAIN%</domain>
+
+   <displayName>Email</displayName>
+   <displayShortName>Email</displayShortName>
+
+   <incomingServer type=\"imap\">
+   <hostname>mailu.example.com</hostname>
+   <port>993</port>
+   <socketType>SSL</socketType>
+   <username>%EMAILADDRESS%</username>
+   <authentication>password-cleartext</authentication>
+   </incomingServer>
+
+   <outgoingServer type=\"smtp\">
+   <hostname>mailu.example.com</hostname>
+   <port>465</port>
+   <socketType>SSL</socketType>
+   <username>%EMAILADDRESS%</username>
+   <authentication>password-cleartext</authentication>
+   <addThisServer>true</addThisServer>
+   <useGlobalPreferredServer>true</useGlobalPreferredServer>
+   </outgoingServer>
+
+   <documentation url=\"https://mailu.example.com/admin/ui/client\">
+   <descr lang=\"en\">Configure your email client</descr>
+   </documentation>
+   </emailProvider>
+   </clientConfig>\r\n";
+   }
+
+3. setup the appropriate DNS/CNAME record (``autoconfig.example.com`` -> ``mailu.example.com``).
+
+*issue reference:* `224`_.
+
+.. _`224`: https://github.com/Mailu/Mailu/issues/224
+.. _`XML file for autoconfiguration`: https://wiki.mozilla.org/Thunderbird:Autoconfiguration:ConfigFileFormat
+
 Technical issues
 ----------------
 
diff --git a/towncrier/newsfragments/224.enhancement b/towncrier/newsfragments/224.enhancement
new file mode 100644
index 00000000..9e4edccf
--- /dev/null
+++ b/towncrier/newsfragments/224.enhancement
@@ -0,0 +1 @@
+Document how to setup client autoconfig using an override