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
-----------

#2 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;