chore: add descriptions to nixos options

Author: felbinger

modules/acme.nix

@@ -8,14 +8,30 @@
     useStagingEnvironment = lib.mkOption {
       type = lib.types.bool;
       default = false;
+      description = ''
+        Whether to use the Let's Encrypt staging environment.
+        The staging environment has much higher rate limits, making it ideal for testing,
+        but the certificates it issues are not trusted by browsers or other clients.
+        Enable this during development or testing to avoid hitting production rate limits.
+      '';
     };
     acmeMail = lib.mkOption {
       type = lib.types.str;
       default = "[email protected]";
+      description = ''
+        The email address to associate with certificate requests to Let's Encrypt.
+        This is used for important account notifications, such as expiry warnings,
+        and may be required by some ACME servers for registration.
+      '';
     };
     renewalNetNs = lib.mkOption {
       type = with lib.types; nullOr str;
       default = null;
+      description = ''
+        The network namespace in which the ACME systemd services will run.
+        If unset, the service runs in the default (global) network namespace.
+        Example: Use a dedicated netns with unrestricted outbound traffic for Let's Encrypt.
+      '';
     };
   };
   config = lib.mkIf ((builtins.length (builtins.attrNames config.security.acme.certs)) > 0) {

modules/cryptpad.nix

@@ -10,14 +10,40 @@
     # https://docs.cryptpad.org/en/dev_guide/general.html
     domain = lib.mkOption {
       type = lib.types.str;
-      default = "ucryptpad.${toString config.networking.fqdn}";
+      default = "cryptpad.${toString config.networking.fqdn}";
+      description = ''
+        The primary (unsafe) domain where CryptPad's sensitive data layer is loaded.
+        This URL handles encrypted user content in memory (drive, contacts, teams),
+        and must be served over HTTPS in production.
+
+        Security note: Vulnerabilities in the UI won't expose this layer's data
+        due to sandboxing, but this domain still requires strict security headers.
+      '';
     };
     sandboxDomain = lib.mkOption {
       type = lib.types.str;
-      default = "cryptpad.${toString config.networking.fqdn}";
+      default = "sandbox.cryptpad.${toString config.networking.fqdn}";
+      description = ''
+        The isolated sandbox domain (loaded in an iframe) that renders the UI.
+        This domain never receives sensitive user data - it only displays document content
+        passed through the sandboxing system.
+
+        Operational note: Must share the same top-level domain as
+        the unsafe origin for cookie/tracking purposes.
+      '';
+    };
+    internal_port = lib.mkOption {
+      type = lib.types.port;
+      description = ''
+        The local port the service listens on.
+      '';
+    };
+    internal_ws_port = lib.mkOption {
+      type = lib.types.port;
+      description = ''
+        The local port the websocket listener of the service listens on.
+      '';
     };
-    internal_port = lib.mkOption { type = lib.types.port; };
-    internal_ws_port = lib.mkOption { type = lib.types.port; };
   };
 
   config = lib.mkIf config.secshell.cryptpad.enable {

modules/filebeat.nix

@@ -4,6 +4,12 @@
     enable = lib.mkEnableOption "filebeat";
     graylogDomain = lib.mkOption {
       type = lib.types.str;
+      description = ''
+        The Graylog server domain or IP address where logs should be sent.
+        This should include the protocol and port if different from default:
+        - For GELF over TCP: `tcp://graylog.example.com:12201`
+        - For HTTP/HTTPS: `https://graylog.example.com:9000/api`
+      '';
     };
   };
   config = lib.mkIf config.secshell.filebeat.enable {

modules/gitea-actions.nix

@@ -1,5 +1,4 @@
 {
-  options,
   config,
   pkgs,
   lib,
@@ -52,6 +51,7 @@ in
       giteaServer = lib.mkOption {
         type = lib.types.str;
         default = config.services.gitea.settings.server.ROOT_URL;
+        description = "The gitea server to serve gitea actions for.";
       };
 
       storeDependencies = lib.mkOption {

modules/gitea.nix

@@ -20,52 +20,106 @@ in
       type = types.str;
       default = "git.${toString config.networking.fqdn}";
       defaultText = "git.\${toString config.networking.fqdn}";
+      description = ''
+        The primary domain name for this service.
+        Used for virtual host configuration, TLS certificates, and service URLs.
+      '';
+    };
+    internal_port = mkOption {
+      type = types.port;
+      description = ''
+        The local port the service listens on.
+      '';
     };
-    internal_port = mkOption { type = types.port; };
     useLocalDatabase = mkOption {
       type = types.bool;
       default = true;
+      description = ''
+        Whether to use a local database instance for this service.
+        When enabled (default), the service will deploy and manage
+        its own postgres database. When disabled, you must configure external
+        database connection parameters separately.
+      '';
     };
     smtp = {
       hostname = mkOption {
         type = types.nullOr types.str;
         default = null;
+        example = "mail.secshell.net";
+        description = ''
+          SMTP server hostname for outgoing email.
+          Leave null to disable email functionality.
+        '';
       };
       from = mkOption {
         type = types.nullOr types.str;
         default = null;
+        example = "[email protected]";
+        description = ''
+          The email address shown as the sender in outgoing emails.
+
+          Important: When this doesn't match the SMTP service account's email address,
+          you must configure your mailserver to allow sending from this address (alias or sender rewriting)
+        '';
       };
       port = mkOption {
         type = types.port;
         default = 587;
+        example = 465;
+        description = ''
+          SMTP server port. STARTTLS uses 587, TLS uses 465 by default.
+        '';
       };
       user = mkOption {
         type = types.nullOr types.str;
         default = null;
+        description = ''
+          SMTP authentication username.
+          Typically the full email address of the service account which is being used to send mails..
+        '';
       };
       noReplyAddress = mkOption {
         type = types.nullOr types.str;
         default = config.secshell.gitea.from;
         defaultText = "config.secshell.gitea.from";
+        example = "[email protected]";
+        description = ''
+          "From" address for automated/non-reply emails.
+        '';
       };
     };
     database = {
       hostname = mkOption {
         type = types.str;
         default = "";
+        description = ''
+          Database server hostname. Not required if local database is being used.
+        '';
       };
       username = mkOption {
         type = types.str;
         default = "gitea";
+        description = ''
+          Database user account with read/write privileges.
+          For PostgreSQL, ensure the user has CREATEDB permission
+          for initial setup if creating databases automatically.
+        '';
       };
       name = mkOption {
         type = types.str;
         default = "gitea";
+        description = ''
+          Name of the database to use.
+          Will be created automatically if the user has permissions.
+        '';
       };
     };
     appName = mkOption {
       type = types.str;
       default = "Secure Shell Networks: Gitea";
+      description = ''
+        The application name of the gitea instance.
+      '';
     };
     sshPort = mkOption {
       type = types.port;
@@ -74,18 +128,33 @@ in
     requireSignInView = mkOption {
       type = types.bool;
       default = true;
+      description = ''
+        Enable this to force users to log in to view any page or to use API.
+        It could be set to "expensive" to block anonymous users accessing some
+        pages which consume a lot of resources, for example: block anonymous AI
+        crawlers from accessing repo code pages. The "expensive" mode is experimental
+        and subject to change.
+      '';
     };
     enableNotifyMail = mkOption {
       type = types.bool;
       default = true;
+      description = ''
+        Enable this to send e-mail to watchers of a repository when something happens,
+        like creating issues. Requires Mailer to be enabled.
+      '';
     };
     allowOnlyExternalRegistrations = mkOption {
       type = types.bool;
       default = true;
+      description = ''
+        Set to true to force registration only using third-party services.
+      '';
     };
     defaultKeepEmailPrivate = mkOption {
       type = types.bool;
       default = true;
+      description = "By default set users to keep their email address private.";
     };
   };
 

modules/graylog.nix

@@ -20,8 +20,15 @@ in
       type = types.str;
       default = "graylog.${toString config.networking.fqdn}";
       defaultText = "graylog.\${toString config.networking.fqdn}";
+      description = ''
+        The primary domain name for this service.
+        Used for virtual host configuration, TLS certificates, and service URLs.
+      '';
+    };
+    internal_port = mkOption {
+      type = types.port;
+      description = "The local port the service listens on.";
     };
-    internal_port = mkOption { type = types.port; };
   };
   config = mkIf cfg.enable {
     sops.secrets."graylog/rootPassword".owner = "graylog";

modules/hedgedoc.nix

@@ -17,39 +17,76 @@ in
       type = types.str;
       default = "md.${toString config.networking.fqdn}";
       defaultText = "md.\${toString config.networking.fqdn}";
+      description = ''
+        The primary domain name for this service.
+        Used for virtual host configuration, TLS certificates, and service URLs.
+      '';
+    };
+    internal_port = mkOption {
+      type = types.port;
+      description = ''
+        The local port the service listens on.
+      '';
     };
-    internal_port = mkOption { type = types.port; };
     useLocalDatabase = mkOption {
       type = types.bool;
       default = true;
+      description = ''
+        Whether to use a local database instance for this service.
+        When enabled (default), the service will deploy and manage
+        its own postgres database. When disabled, you must configure external
+        database connection parameters separately.
+      '';
     };
     database = {
       hostname = mkOption {
         type = types.str;
         default = "/run/postgresql";
+        description = ''
+          Database server hostname. Not required if local database is being used.
+        '';
       };
       username = mkOption {
         type = types.str;
         default = "hedgedoc";
+        description = ''
+          Database user account with read/write privileges.
+          For PostgreSQL, ensure the user has CREATEDB permission
+          for initial setup if creating databases automatically.
+        '';
       };
       name = mkOption {
         type = types.str;
         default = "hedgedoc";
+        description = ''
+          Name of the database to use.
+          Will be created automatically if the user has permissions.
+        '';
       };
     };
     oidc = {
       domain = mkOption {
         type = types.str;
         default = "";
+        description = ''
+          The open id connect server used for authentication.
+          Leave null to disable oidc authentication.
+        '';
       };
       realm = mkOption {
         type = types.str;
         default = "main";
+        description = ''
+          The realm to use for the open id connect authentication.
+        '';
       };
       clientId = mkOption {
         type = types.str;
         default = cfg.domain;
         defaultText = "config.secshell.hedgedoc.domain";
+        description = ''
+          The client id for the open id connect authentication.
+        '';
       };
     };
   };