Contribute or troubleshoot

To report an issue, please go to https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/issues.

If you have questions, feel free to reach out:

All our workflows rely on Nix being configured with Flakes.

Development Shell

We provide a flake.nix devshell that automatically sets up pre-commit hooks, which allows for fast feedback cycles when making changes to the repository.

$ nix develop

We recommend setting up direnv to automatically attach to the development environment when entering the project directories.

Run NixOS tests

To run the test suite, you need to enable Nix Flakes.

You can then run the testsuite via

$ nix flake check -L

Since Nix doesn't garantee your machine have enough resources to run all test VMs in parallel, some tests can fail. You would then haev to run tests manually. For instance:

$ nix build .#hydraJobs.x86_64-linux.external-unstable -L

Contributing to the documentation

The documentation is written in RST (except option documentation which is in CommonMark), built with Sphinx and published by Read the Docs.

For the syntax, see the RST/Sphinx primer.

To build the documentation, you need to enable Nix Flakes.

$ nix build .#documentation
$ xdg-open result/index.html

Manual migrations

We need to take great care around providing a migration story around breaking changes. If manual intervention becomes necessary we provide the stateVersion option to notify the user that they need to complete a migration before they can deploy an update.

If that is the case for your change, find the highest stateVersion that is being asserted on in mail-server/assertions.nix. Then pick the next number and add a new assertion, write a good summary describing the issue and what remediation steps are necessary. Finally reference the URL to the specific section on the migration page in the documentation.

{
  assertions = [
    {
      assertion = config.mailserver.stateVersion >= 1;
      message = ''
        Problem: The home directory for the foobar service is snafu.
        Remediation:
          - Stop the `foobar.service`
          - Rename `/var/lib/foobaz` to `/var/lib/foobar`
          - Increase the `mailserver.stateVersion` to 1.

        Check https://nixos-mailserver.readthedocs.io/en/latest/migrations.html#specific-anchor-here for further details.
      '';
    }
  ];
}

The setup guide should always reference the latest stateVersion, since we don't require any migration steps for new setups.

The migration documentation should paint a more complete picture about the steps that need to be carried out and why this has become necessary. Make sure to reference the correct anchor in the URL you put into the assertion message.