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

Adds a short explanation what roundcube even is.

Extract and extend the roundcube example showing plugin and spellchecking
support. We also inherit a plausible maximum attachment size based on
Postfix's message_size_limit. The nginx vhost forces TLS and manages
certificates using the ACME integration.
---
 docs/add-roundcube.rst | 31 -------------------------------
 docs/index.rst         |  2 +-
 docs/roundcube.nix     | 41 +++++++++++++++++++++++++++++++++++++++++
 docs/roundcube.rst     | 19 +++++++++++++++++++
 4 files changed, 61 insertions(+), 32 deletions(-)
 delete mode 100644 docs/add-roundcube.rst
 create mode 100644 docs/roundcube.nix
 create mode 100644 docs/roundcube.rst

diff --git a/docs/add-roundcube.rst b/docs/add-roundcube.rst
deleted file mode 100644
index 06c7b2f..0000000
--- a/docs/add-roundcube.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-Add Roundcube, a webmail
-========================
-
-The NixOS module for roundcube nearly works out of the box with SNM. By
-default, it sets up a nginx virtual host to serve the webmail, other web
-servers may require more work.
-
-.. code:: nix
-
-   { config, pkgs, lib, ... }:
-
-   with lib;
-
-   {
-     services.roundcube = {
-        enable = true;
-        # this is the url of the vhost, not necessarily the same as the fqdn of
-        # the mailserver
-        hostName = "webmail.example.com";
-        extraConfig = ''
-          $config['imap_host'] = "ssl://${config.mailserver.fqdn}";
-          $config['smtp_host'] = "ssl://${config.mailserver.fqdn}";
-          $config['smtp_user'] = "%u";
-          $config['smtp_pass'] = "%p";
-        '';
-     };
-
-     services.nginx.enable = true;
-
-     networking.firewall.allowedTCPPorts = [ 80 443 ];
-   }
diff --git a/docs/index.rst b/docs/index.rst
index d6e7465..469e876 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,7 +35,7 @@ Welcome to NixOS Mailserver's documentation!
 
    backup-guide
    radicale
-   add-roundcube
+   roundcube
    rspamd-tuning
    flakes
    autodiscovery
diff --git a/docs/roundcube.nix b/docs/roundcube.nix
new file mode 100644
index 0000000..5ec7efb
--- /dev/null
+++ b/docs/roundcube.nix
@@ -0,0 +1,41 @@
+{
+  config,
+  pkgs,
+  ...
+}:
+
+{
+  services.roundcube = {
+    enable = true;
+    hostName = "webmail.example.com"; # the nginx vhost
+    package = pkgs.roundcube.withPlugins (
+      plugins: with plugins; [
+        # https://search.nixos.org/packages?query=roundcubePlugins
+        persistent_login
+      ]
+    );
+    dicts = with pkgs.aspellDicts; [
+      # https://search.nixos.org/packages?query=aspellDicts
+      en
+    ];
+    # Account for ~30% size increase due to base64 encoding of attachments
+    # https://github.com/roundcube/roundcubemail/issues/7979
+    maxAttachmentSize = config.mailserver.messageSizeLimit / 1024 / 1024 / 1.37;
+    extraConfig = ''
+      $config['imap_host'] = "ssl://${config.mailserver.fqdn}";
+      $config['smtp_host'] = "ssl://${config.mailserver.fqdn}";
+      $config['smtp_user'] = "%u";
+      $config['smtp_pass'] = "%p";
+    '';
+  };
+
+  services.nginx.virtualHosts.${config.services.rounducbe.hostName} = {
+    enableACME = true;
+    forceSSL = true;
+  };
+
+  networking.firewall.allowedTCPPorts = [
+    80
+    443
+  ];
+}
diff --git a/docs/roundcube.rst b/docs/roundcube.rst
new file mode 100644
index 0000000..c1f99ee
--- /dev/null
+++ b/docs/roundcube.rst
@@ -0,0 +1,19 @@
+Roundcube
+=========
+
+Roundcube is a browser-based open-source webmail client that provides a
+full-featured email interface with support for IMAP, SMTP, address books, and
+extensible plugins.
+
+Code
+^^^^
+
+The NixOS module for Roundcube integrates almost immediately with NixOS
+mailserver, automatically configuring an Nginx virtual host and ACME-managed
+TLS for secure webmail access; using other web servers may require additional
+manual setup.
+
+Once set up you can login with your login account credentials.
+
+.. literalinclude:: ./roundcube.nix
+   :language: nix