misc_nixos-mailserver/docs/migrations.rst

Migrations
==========

With mail server configuration best practices changing over time we might need
to make changes that require you to complete manual migration steps before you
can deploy a new version of NixOS mailserver.

The initial `mailserver.stateVersion` value should be copied from the setup
guide that you used to initially set up your mail server. If in doubt you can
always initialize it at `1` and walk through all assertions, that might apply
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Dovecot configuration for LDAP home directories previously did not respect
the ``mailserver.mailDirectory`` setting.

This means that home directories were unconditionally located at
``/var/vmail/ldap/%{user}``.

This migration is required if you both:

* enabled the LDAP integration (``mailserver.ldap.enable``)
* and customized the default mail directory (``mailserver.mailDirectory != "/var/vmail"``)

For remediating this issue the following steps are required:

1. Stop ``dovecot2.service``.
2. Move ``/var/vmail/ldap`` below your ``m̀ailserver.mailDirectory``.
3. Update the ``mailserver.stateVersion`` to ``2``.

#1 Initialization
^^^^^^^^^^^^^^^^^

This option was introduced in the NixOS 25.11 release cycle, in which case you
can safely initialize its value at `1`.

.. code-block:: nix

   mailserver.stateVersion = 1;