Document bookdb module and options

barrucadu · Oct 15, 2023 · f2f395f · f2f395f
1 parent 3f311c5
commit f2f395f
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 7 deletions.
diff --git a/shared/bookdb/default.nix b/shared/bookdb/default.nix
@@ -1,3 +1,15 @@
+# Webapp to keep track of all my books, deployed to [bookdb.barrucadu.co.uk][].
+#
+# bookdb runs under its own user and uses a containerised elasticsearch
+# database, it also stores uploaded book cover images.
+#
+# If the `backups` module is enabled, adds a script to backup the database and
+# uploaded files.
+#
+# If the `erase-your-darlings` module is enabled, stores its data on the
+# persistent volume.
+#
+# [bookdb.barrucadu.co.uk]: https://bookdb.barrucadu.co.uk/
 { config, lib, pkgs, ... }:
 
 with lib;

diff --git a/shared/bookdb/options.nix b/shared/bookdb/options.nix
@@ -4,12 +4,64 @@ with lib;
 
 {
   options.nixfiles.bookdb = {
-    enable = mkOption { type = types.bool; default = false; };
-    port = mkOption { type = types.int; default = 46667; };
-    esPort = mkOption { type = types.int; default = 47164; };
-    esTag = mkOption { type = types.str; default = "8.0.0"; };
-    baseURI = mkOption { type = types.str; };
-    readOnly = mkOption { type = types.bool; default = false; };
-    dataDir = mkOption { type = types.str; default = "/srv/bookdb"; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `bookdb` module.
+      '';
+    };
+
+    port = mkOption {
+      type = types.int;
+      default = 46667;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the bookdb service on.
+      '';
+    };
+
+    esPort = mkOption {
+      type = types.int;
+      default = 47164;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the elasticsearch container on.
+      '';
+    };
+
+    esTag = mkOption {
+      type = types.str;
+      default = "8.0.0";
+      description = mdDoc ''
+        Tag to use of the `elasticsearch` container image.
+      '';
+    };
+
+    baseURI = mkOption {
+      type = types.str;
+      example = "https://bookdb.barrucadu.co.uk";
+      description = mdDoc ''
+        URI which the service will be exposed on, used to generate URLs.
+      '';
+    };
+
+    readOnly = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Whether to launch the service in "read-only" mode.  Enable this if
+        exposing it to a public network.
+      '';
+    };
+
+    dataDir = mkOption {
+      type = types.str;
+      default = "/srv/bookdb";
+      description = mdDoc ''
+        Directory to store uploaded files to.
+
+        If the `erase-your-darlings` module is enabled, this is overridden to be
+        on the persistent volume.
+      '';
+    };
   };
 }