From 6633da54d4666d56dc119eaebe4efb3fa75ad497 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 15 Dec 2025 11:22:10 +0000
Subject: [PATCH] Document both methods for extending mail_plugins

- Added documentation for using extra.conf with protocol blocks
- Clarified the recommended approach (extra files)
- Explained advantages and considerations of each method

Co-authored-by: DerLinkman <62480600+DerLinkman@users.noreply.github.com>
---
 data/conf/dovecot/dovecot.conf | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/data/conf/dovecot/dovecot.conf b/data/conf/dovecot/dovecot.conf
index 828c23ef1..bc1137480 100644
--- a/data/conf/dovecot/dovecot.conf
+++ b/data/conf/dovecot/dovecot.conf
@@ -1,12 +1,23 @@
 # --------------------------------------------------------------------------
 # Please create a file "extra.conf" for persistent overrides to dovecot.conf
 # --------------------------------------------------------------------------
-# To extend mail_plugins, you can either:
-# 1. Create/edit /etc/dovecot/mail_plugins_extra (for global plugins)
-# 2. Create/edit /etc/dovecot/mail_plugins_imap_extra (for IMAP-specific plugins)
-# 3. Create/edit /etc/dovecot/mail_plugins_lmtp_extra (for LMTP-specific plugins)
-# For example, to add the virtual plugin globally:
-#   echo -n ' virtual' > data/conf/dovecot/mail_plugins_extra
+# To extend mail_plugins, you have two options:
+#
+# Option 1 (Recommended): Use the extra plugin files directly
+#   Create/edit data/conf/dovecot/mail_plugins_extra (for global plugins)
+#   Create/edit data/conf/dovecot/mail_plugins_imap_extra (for IMAP-specific plugins)
+#   Create/edit data/conf/dovecot/mail_plugins_lmtp_extra (for LMTP-specific plugins)
+#   Example to add the virtual plugin globally:
+#     echo -n ' virtual' > data/conf/dovecot/mail_plugins_extra
+#     docker-compose restart dovecot-mailcow
+#
+# Option 2: Override protocol sections in extra.conf
+#   Create data/conf/dovecot/extra.conf with protocol-specific overrides:
+#     protocol imap {
+#       mail_plugins = $mail_plugins virtual
+#     }
+#   Note: This requires redefining the entire protocol block and may override
+#   other settings. Option 1 is simpler and less prone to conflicts.
 # --------------------------------------------------------------------------
 # LDAP example:
 #passdb {