Add documentation on Dovecot

3 files changed, 107 insertions, 0 deletions

diff --git a/docs/docs/services/email/components/dovecot/imap.md b/docs/docs/services/email/components/dovecot/imap.md
new file mode 100644
index 0000000..1cdcda8
--- /dev/null
+++ b/docs/docs/services/email/components/dovecot/imap.md
@@ -0,0 +1,34 @@
+---
+description: Our IMAP configuration for Python Discord
+---
+# IMAP
+
+!!! note
+
+    This is a technical overview of our IMAP configuration, for guidance on
+    setting up and using IMAP, check the [Mail Clients](../../mail-clients.md)
+    documentation.
+
+We use a mostly standard Dovecot configuration, with the primary difference
+being that we make use of the LDAP integrations to provide our `userdb`.
+
+Our IMAP configuration automatically creates the following folders:
+
+| Folder Name        | Purpose                    |
+|--------------------|----------------------------|
+| Inbox              | Newly received mail        |
+| Drafts             | Draft (postponed) messages |
+| Junk               | Mail marked as spam[^1]    |
+| Trash              | Mail deleted by users[^2]  |
+| Sent/Sent Messages | Messages sent by the user  |
+
+Mail is delivered into the `/var/vmail/%USER` directory, owned by the `vmail`
+non-privileged user.
+
+Dovecot then exposes this folder over IMAP and allows user mailbox modification
+using IMAP-compatible mail clients.
+
+[^1]: We have not yet implemented a spam filtering solution and so for now this
+    box contains only mail the user has explicitly marked as junk.
+
+[^2]: Mail in this folder is automatically wiped after 60 days.
diff --git a/docs/docs/services/email/components/dovecot/index.md b/docs/docs/services/email/components/dovecot/index.md
new file mode 100644
index 0000000..1dcc035
--- /dev/null
+++ b/docs/docs/services/email/components/dovecot/index.md
@@ -0,0 +1,56 @@
+---
+description: Overview of Dovecot, our local mail delivery and IMAP daemon.
+---
+# Dovecot
+
+We use [Dovecot](https://www.dovecot.org/) for both local delivery and IMAP access to mailboxes.
+
+<div class="grid cards" markdown>
+
+-   :material-inbox-arrow-down:{ .lg .middle } __Local Delivery__
+
+    ---
+
+    Configuration for delivering inbound mail from Postfix to a directory.
+
+    [:octicons-arrow-right-24: Read more](./local-delivery.md)
+
+-   :simple-thunderbird:{ .lg .middle } __IMAP__
+
+    ---
+
+    Configuration for users accessing mailboxes over IMAP protocol.
+
+    [:octicons-arrow-right-24: Read more](./imap.md)
+
+</div>
+
+## LDAP Users
+
+Dovecot checks against our LDAP directory for users before attempting mail
+delivery or permitting access to a mailbox.
+
+Dovecot performs Bind authentications meaning it tests the credentials provided
+by the user against the LDAP directory, and does not perform the password
+validation itself.
+
+We permit the following login mechanisms:
+
+- `PLAIN` (Plaintext passwords, with security added by TLS/SSL)
+- `LOGIN` (Obsolete, but still used by Microsoft services)
+
+When a user authenticates, we confirm the login with the LDAP directory and
+permit access, either to the SMTP server via Dovecot SASL or to IMAP via Dovecot
+authentication.
+
+## Administration
+
+Dovecot mostly services itself, you can check the logs by looking for
+`dovecot.service` in the system journal.
+
+You can perform a selection of administration tasks with the `doveadm` tool,
+which has a great manpage.
+
+This includes things like testing LDAP lookups (`doveadm user`), listing folders
+in a user mailbox (`doveadm mailbox`), or viewing Dovecot service status
+(`dovecot process status`).
diff --git a/docs/docs/services/email/components/dovecot/local-delivery.md b/docs/docs/services/email/components/dovecot/local-delivery.md
new file mode 100644
index 0000000..6f5b039
--- /dev/null
+++ b/docs/docs/services/email/components/dovecot/local-delivery.md
@@ -0,0 +1,17 @@
+---
+description: Configuration for getting mail delivered to Postfix into a local folder
+---
+# Local Delivery
+
+We use the Dovecot LMTP daemon to deliver mail destined to local mailboxes (i.e.
+that has not been forwarded or processed by a service) into the relevant folders
+for IMAP consumption.
+
+As shown in the [Postfix Overview](../../services/postfix.md), mail destined to
+local addresses is sent to the Dovecot LMTP agent to be placed into the relevant
+`/var/vmail` folder.
+
+Postfix still performs all pre-delivery checks and handles rejections for
+messages that have not met the delivery criteria (i.e. spoofed SPF or DKIM).
+
+*[LMTP]: Local Mail Transfer Protocol