dovecot: migrate to dedicated homedir and separate maildir paths

Per the dovecot documentation[0] we were previously running with an
unsupported home directory configuration, because we shared them among
all virtual users at /var/vmail.

After resolving this by creating per user home directories at
/var/vmail/%{domain}/%{user} this now also overlaps with the location of
the Maildir, which is not recommended.

As a result we now need to migrate our Maildirs into
/var/vmail/%{domain}/%{user}/mail, for which a small shell script is
provided as part of this change.

The script is included in the documentation because we cannot provide it
in time for users, because they might already be seeing the relevant
assertion and there is no safe waiting period that would allow us to skip
shipping it like that.

[0] https://doc.dovecot.org/2.3/configuration_manual/mail_location/

docs/migrations.rst

@@ -13,6 +13,75 @@ to your setup.
 NixOS 25.11
 -----------
 
+#3 Dovecot mail directory migration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The way the Dovecot home directory for login accounts were previously set up
+resulted in shared home directories for all those users. This is not a
+supported Dovecot configuration.
+
+To resolve this we migrated the home directory into the individual
+`domain/localpart` subdirectory below the `mailserver.mailDirectory`.
+
+But since this now overlaps with the location of the Maildir, it must be
+migrated into the `mail/` directory below the home directory.
+And while the LDAP home directory is not affected we use this migration to
+keep the Maildir configurations of LDAP users in sync with those of local
+accounts.
+
+This is a big step forward, since we can now more cleanly colocate other
+data directories, like sieve in the home directory, which in turn simplifies
+backups.
+
+This migration is required for every configuration.
+
+For remediating this issue the following steps are required:
+
+1. Copy the `migration script <https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/blob/master/migrations/nixos-mailserver-migration-03.py>`_ script to your mailserver
+   and make it executable:
+
+   .. code-block:: bash
+
+      wget https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/raw/master/migrations/nixos-mailserver-migration-03.py
+      chmod +x nixos-mailserver-migration-03.py
+
+2. Stop the ``dovecot2.service``.
+
+   .. code-block:: bash
+
+      systemctl stop dovecot2.service
+
+3. Create a backup or snapshot of your ``mailserver.mailDirectory``, so you can restore
+   should anything go wrong.
+
+4. Run the migration script under your virtual mail user with the following arguments:
+
+   - ``--layout default`` unless ``useFSLayout`` is enabled, then ``--layout folder``
+   - The value of ``mailserver.mailDirectory``, which defaults to ``/var/vmail``
+
+   The script will not modify your data unless called with ``--execute``.
+
+   Example:
+
+   .. code-block:: bash
+
+      sudo -u virtualMail ./nixos-mailserver-migration-03.py --layout default /var/vmail
+
+5. Review the commands. They should be
+
+   - create a ``mail`` directory for each accounnt,
+   - move maildir contents from the parent directory into it,
+   - suggest removal of files that do not belong to the maildir
+
+      - their removal is not mandatory and the script **will not** remove them when called with ``--execute``
+      - review these items carefully if you want to remove them yourself
+
+   - remove obsolete files from the old home directory location
+
+6. Rerun the command with ``--execute`` or run the commands manually.
+
+7. Update the ``mailserver.stateVersion`` to ``3``.
+
 #2 Dovecot LDAP home directory migration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/setup-guide.rst

@@ -72,7 +72,7 @@ common ones.
 
      mailserver = {
        enable = true;
-       stateVersion = 2;
+       stateVersion = 3;
        fqdn = "mail.example.com";
        domains = [ "example.com" ];