Document concourse module and options

barrucadu · Oct 15, 2023 · 67de8fe · 67de8fe
1 parent e78cb05
commit 67de8fe
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 8 deletions.
diff --git a/shared/concourse/default.nix b/shared/concourse/default.nix
@@ -1,3 +1,17 @@
+# [Concourse CI][] is a "continuous thing-doer", it's a CI / CD tool.  This
+# module sets up a single-user instance, with GitHub authentication.
+#
+# Concourse uses a containerised postgres database.
+#
+# If the `backups` module is enabled, adds a script to backup the database.
+#
+# If the `erase-your-darlings` module is enabled, stores its data on the
+# persistent volume.
+#
+# Enabling this module also provisions a [Grafana][] dashboard.
+#
+# [Concourse CI]: https://concourse-ci.org/
+# [Grafana]: https://grafana.com/
 { config, lib, pkgs, ... }:
 
 with lib;

diff --git a/shared/concourse/options.nix b/shared/concourse/options.nix
@@ -4,13 +4,75 @@ with lib;
 
 {
   options.nixfiles.concourse = {
-    enable = mkOption { type = types.bool; default = false; };
-    concourseTag = mkOption { type = types.str; default = "7.8.2"; };
-    githubUser = mkOption { type = types.str; default = "barrucadu"; };
-    port = mkOption { type = types.int; default = 46498; };
-    metricsPort = mkOption { type = types.int; default = 45811; };
-    postgresTag = mkOption { type = types.str; default = "13"; };
-    workerScratchDir = mkOption { type = types.nullOr types.path; default = null; };
-    environmentFile = mkOption { type = types.str; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `concourse` module.
+      '';
+    };
+
+    concourseTag = mkOption {
+      type = types.str;
+      default = "7.8.2";
+      description = mdDoc ''
+        Tag to use of the `concourse/concourse` container image.
+      '';
+    };
+
+    githubUser = mkOption {
+      type = types.str;
+      default = "barrucadu";
+      description = mdDoc ''
+        The GitHub user to authenticate with.
+      '';
+    };
+
+    port = mkOption {
+      type = types.int;
+      default = 46498;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the concourse service on.
+      '';
+    };
+
+    metricsPort = mkOption {
+      type = types.int;
+      default = 45811;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the concourse prometheus metrics on.
+      '';
+    };
+
+    postgresTag = mkOption {
+      type = types.str;
+      default = "13";
+      description = mdDoc ''
+        Tag to use of the `postgres` container image.
+      '';
+    };
+
+    workerScratchDir = mkOption {
+      type = types.nullOr types.path;
+      default = null;
+      description = mdDoc ''
+        Mount a directory from the host into the worker container to use as
+        temporary storage.  This is useful if the filesystem used for container
+        volumes isn't very big.
+      '';
+    };
+
+    environmentFile = mkOption {
+      type = types.str;
+      description = mdDoc ''
+        Environment file to be passed into the containers.  This needs to contain:
+
+        - `CONCOURSE_GITHUB_CLIENT_ID` / `CONCOURSE_GITHUB_CLIENT_SECRET` - the
+          GitHub OAuth credentials used for user authentication
+        - `CONCOURSE_AWS_SSM_REGION` / `CONCOURSE_AWS_SSM_ACCESS_KEY` /
+          `CONCOURSE_AWS_SSM_SECRET_KEY` - the AWS credentials used to fetch
+          secrets from SSM
+      '';
+    };
   };
 }