From cff7a27cfe434c3ed18607872c3c4a54faf93e87 Mon Sep 17 00:00:00 2001
From: Martin Weinelt <hexa@darmstadt.ccc.de>
Date: Tue, 10 Mar 2026 02:02:53 +0100
Subject: [PATCH] docs: update Radicale guide

We now explain what Radicale even is and classify reusing the hashed
passwords of login accounts as limitation because it requires using
compatible password hashes.

This is difficult because compatible password hashes need an overlap
between libxcrypt and Radicales choice of libraries: libpass, argon2 and
bcrypt.

Extract the source code into a proper .nix file so we get source linting
and formatting for free. Pruned from bad practices of the past, like
global `with lib`.
---
 docs/add-radicale.rst | 55 -------------------------------------------
 docs/index.rst        |  2 +-
 docs/radicale.nix     | 55 +++++++++++++++++++++++++++++++++++++++++++
 docs/radicale.rst     | 29 +++++++++++++++++++++++
 4 files changed, 85 insertions(+), 56 deletions(-)
 delete mode 100644 docs/add-radicale.rst
 create mode 100644 docs/radicale.nix
 create mode 100644 docs/radicale.rst

diff --git a/docs/add-radicale.rst b/docs/add-radicale.rst
deleted file mode 100644
index cf98333..0000000
--- a/docs/add-radicale.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-Add Radicale
-============
-
-Configuration by @dotlambda
-
-Starting with Radicale 3 (first introduced in NixOS 20.09) the traditional
-crypt passwords are no longer supported.  Instead bcrypt passwords
-have to be used. These can still be generated using `mkpasswd -m bcrypt`.
-
-.. code:: nix
-
-   { config, pkgs, lib, ... }:
-
-   with lib;
-
-   let
-     mailAccounts = config.mailserver.loginAccounts;
-     htpasswd = pkgs.writeText "radicale.users" (concatStrings
-       (flip mapAttrsToList mailAccounts (mail: user:
-         mail + ":" + user.hashedPassword + "\n"
-       ))
-     );
-
-   in {
-     services.radicale = {
-       enable = true;
-       settings = {
-         auth = {
-           type = "htpasswd";
-           htpasswd_filename = "${htpasswd}";
-           htpasswd_encryption = "bcrypt";
-         };
-       };
-     };
-
-     services.nginx = {
-       enable = true;
-       virtualHosts = {
-         "cal.example.com" = {
-           forceSSL = true;
-           enableACME = true;
-           locations."/" = {
-             proxyPass = "http://localhost:5232/";
-             extraConfig = ''
-               proxy_set_header  X-Script-Name /;
-               proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
-               proxy_pass_header Authorization;
-             '';
-           };
-         };
-       };
-     };
-
-     networking.firewall.allowedTCPPorts = [ 80 443 ];
-   }
diff --git a/docs/index.rst b/docs/index.rst
index 2cb5339..d6e7465 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,7 +34,7 @@ Welcome to NixOS Mailserver's documentation!
    :caption: How-to
 
    backup-guide
-   add-radicale
+   radicale
    add-roundcube
    rspamd-tuning
    flakes
diff --git a/docs/radicale.nix b/docs/radicale.nix
new file mode 100644
index 0000000..e740fb7
--- /dev/null
+++ b/docs/radicale.nix
@@ -0,0 +1,55 @@
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+
+let
+  inherit (lib)
+    concatStrings
+    flip
+    mapAttrsToList
+    ;
+
+  mailAccounts = config.mailserver.loginAccounts;
+  htpasswd = pkgs.writeText "radicale.users" (
+    concatStrings (flip mapAttrsToList mailAccounts (mail: user: "${mail}+:${user.hashedPassword}\n"))
+  );
+
+in
+{
+  services.radicale = {
+    enable = true;
+    settings = {
+      auth = {
+        type = "htpasswd";
+        htpasswd_filename = "${htpasswd}";
+        htpasswd_encryption = "bcrypt";
+      };
+    };
+  };
+
+  services.nginx = {
+    enable = true;
+    virtualHosts = {
+      "cal.example.com" = {
+        forceSSL = true;
+        enableACME = true;
+        locations."/" = {
+          proxyPass = "http://localhost:5232/";
+          extraConfig = ''
+            proxy_set_header  X-Script-Name /;
+            proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_pass_header Authorization;
+          '';
+        };
+      };
+    };
+  };
+
+  networking.firewall.allowedTCPPorts = [
+    80
+    443
+  ];
+}
diff --git a/docs/radicale.rst b/docs/radicale.rst
new file mode 100644
index 0000000..244a41e
--- /dev/null
+++ b/docs/radicale.rst
@@ -0,0 +1,29 @@
+Radicale
+========
+
+Radicale is a lightweight open-source CalDAV/CardDAV server that stores
+calendars and contacts as plain files on the filesystem, enabling simple
+self-hosted synchronization with standard clients.
+
+Limitations
+^^^^^^^^^^^
+
+Radicale since the 3.x release (introduced in NixOS 20.09) does not support
+traditional crypt() password hashes any longer. To establish access for
+existing :option:`mailserver.loginAccounts`, the hashing method used
+for ``hashedPassword`` needs to be compatible with one of the available
+`htpasswd_encryption`_ methods. Such hashes can for example be created using
+
+.. code-block:: console
+
+   nix-shell -p mkpasswd --command "mkpasswd -m bcrypt"
+
+.. _htpasswd_encryption: https://radicale.org/v3.html#htpasswd_encryption
+
+Code
+^^^^
+
+Configuration contributed by Robert Schütz (@dotlambda).
+
+.. literalinclude:: ./radicale.nix
+   :language: nix