From 089d996a9ab22c52bd4bdbeffeb8deff362efefc Mon Sep 17 00:00:00 2001 From: Michael Walker Date: Mon, 16 Oct 2023 18:43:04 +0100 Subject: [PATCH] Editing pass to make option docs consistent --- shared/backups/options.nix | 21 ++++++++++++++------- shared/bookdb/options.nix | 8 ++++---- shared/bookmarks/options.nix | 17 +++++++++++------ shared/concourse/options.nix | 23 ++++++++++++++--------- shared/erase-your-darlings/options.nix | 3 +-- shared/finder/options.nix | 4 ++-- shared/foundryvtt/options.nix | 2 +- shared/minecraft/options.nix | 4 ++-- shared/oci-containers/options.nix | 24 ++++++++++++++---------- shared/options.nix | 8 +++++++- shared/pleroma/options.nix | 8 ++++---- shared/resolved/options.nix | 2 +- shared/rtorrent/options.nix | 6 +++--- shared/umami/options.nix | 9 ++++++--- 14 files changed, 84 insertions(+), 55 deletions(-) diff --git a/shared/backups/options.nix b/shared/backups/options.nix index 8549f275..8aaf48fb 100644 --- a/shared/backups/options.nix +++ b/shared/backups/options.nix @@ -62,16 +62,23 @@ with lib; environmentFile = mkOption { type = types.str; description = mdDoc '' - Environment file to be passed to the systemd services. This needs to contain: + Environment file to pass secrets into the service. This is of the form: - - `PASSPHRASE` - the password duplicity uses to encrypt the files - - `AWS_ACCESS_KEY` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION` - - the AWS credentials used to upload the backup to s3 and publish to the - SNS topic - - `TOPIC_ARN` - the SNS topic to publish to if an error occurs + ```text + # Duplicity encryption password + PASSPHRASE="..." + + # AWS S3 & SNS credentials + AWS_ACCESS_KEY="..." + AWS_SECRET_ACCESS_KEY="..." + AWS_DEFAULT_REGION="..." + + # SNS topic to send alerts to + TOPIC_ARN="..." + ``` If any of the `scripts` or `pythonScripts` need secrets, those should be - specified here. + specified in this file as well. ''; }; diff --git a/shared/bookdb/options.nix b/shared/bookdb/options.nix index df9b360c..93b13624 100644 --- a/shared/bookdb/options.nix +++ b/shared/bookdb/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the bookdb service. + Enable the [bookdb](https://github.com/barrucadu/bookdb) service. ''; }; @@ -16,7 +16,7 @@ with lib; type = types.int; default = 46667; description = mdDoc '' - Port (on 127.0.0.1) to expose the bookdb service on. + Port (on 127.0.0.1) to expose bookdb on. ''; }; @@ -48,8 +48,8 @@ with lib; 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. + Launch the service in "read-only" mode. Enable this if exposing it to a + public network. ''; }; diff --git a/shared/bookmarks/options.nix b/shared/bookmarks/options.nix index 60d5a3f4..e670d65a 100644 --- a/shared/bookmarks/options.nix +++ b/shared/bookmarks/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the bookmarks service. + Enable the [bookmarks](https://github.com/barrucadu/bookmarks) service. ''; }; @@ -16,7 +16,7 @@ with lib; type = types.int; default = 48372; description = mdDoc '' - Port (on 127.0.0.1) to expose the bookmarks service on. + Port (on 127.0.0.1) to expose bookmarks on. ''; }; @@ -48,8 +48,8 @@ with lib; 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. + Launch the service in "read-only" mode. Enable this if exposing it to a + public network. ''; }; @@ -57,8 +57,13 @@ with lib; type = types.nullOr types.str; default = null; description = mdDoc '' - Environment file to be passed to the systemd services. This needs to - contain a `YOUTUBE_API_KEY` if not running in read-only mode. + Environment file to pass secrets into the service. This is of the form: + + ```text + YOUTUBE_API_KEY="..." + ``` + + This is only required if not running in read-only mode. ''; }; }; diff --git a/shared/concourse/options.nix b/shared/concourse/options.nix index 531da34d..aeeb68c4 100644 --- a/shared/concourse/options.nix +++ b/shared/concourse/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the Concourse CI service. + Enable the [Concourse CI](https://concourse-ci.org/) service. ''; }; @@ -32,7 +32,7 @@ with lib; type = types.int; default = 46498; description = mdDoc '' - Port (on 127.0.0.1) to expose the Concourse CI web UI on. + Port (on 127.0.0.1) to expose Concourse CI on. ''; }; @@ -40,7 +40,7 @@ with lib; type = types.int; default = 45811; description = mdDoc '' - Port (on 127.0.0.1) to expose the Concourse CI Prometheus metrics on. + Port (on 127.0.0.1) to expose the Prometheus metrics on. ''; }; @@ -65,13 +65,18 @@ with lib; environmentFile = mkOption { type = types.str; description = mdDoc '' - Environment file to be passed into the containers. This needs to contain: + Environment file to pass secrets into the service. This is of the form: - - `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 + ```text + # GitHub OAuth credentials + CONCOURSE_GITHUB_CLIENT_ID="..." + CONCOURSE_GITHUB_CLIENT_SECRET="..." + + # AWS SSM credentials + CONCOURSE_AWS_SSM_REGION="..." + CONCOURSE_AWS_SSM_ACCESS_KEY="..." + CONCOURSE_AWS_SSM_SECRET_KEY="..." + ``` ''; }; }; diff --git a/shared/erase-your-darlings/options.nix b/shared/erase-your-darlings/options.nix index 79184194..75f565ff 100644 --- a/shared/erase-your-darlings/options.nix +++ b/shared/erase-your-darlings/options.nix @@ -16,8 +16,7 @@ with lib; barrucaduPasswordFile = mkOption { type = types.str; description = mdDoc '' - Path to a file containing the hashed password for `barrucadu`. This - file must be available in early boot. + File containing the hashed password for `barrucadu`. If using [sops-nix](https://github.com/Mic92/sops-nix) set the `neededForUsers` option on the secret. diff --git a/shared/finder/options.nix b/shared/finder/options.nix index 7b849969..9f922ece 100644 --- a/shared/finder/options.nix +++ b/shared/finder/options.nix @@ -15,7 +15,7 @@ with lib; image = mkOption { type = types.str; description = mdDoc '' - Container image to use. + Container image to run. ''; }; @@ -23,7 +23,7 @@ with lib; type = types.int; default = 44986; description = mdDoc '' - Port (on 127.0.0.1) to expose the finder service on. + Port (on 127.0.0.1) to expose finder on. ''; }; diff --git a/shared/foundryvtt/options.nix b/shared/foundryvtt/options.nix index 45144527..ca52bb67 100644 --- a/shared/foundryvtt/options.nix +++ b/shared/foundryvtt/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the FoundryVTT service. + Enable the [FoundryVTT](https://foundryvtt.com/) service. ''; }; diff --git a/shared/minecraft/options.nix b/shared/minecraft/options.nix index 7f8a4f03..76e45a7a 100644 --- a/shared/minecraft/options.nix +++ b/shared/minecraft/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the Minecraft service. + Enable the [Minecraft](https://www.minecraft.net/en-us) service. ''; }; @@ -31,7 +31,7 @@ with lib; type = types.bool; default = true; description = mdDoc '' - Start this server on boot. + Start the server automatically on boot. ''; }; diff --git a/shared/oci-containers/options.nix b/shared/oci-containers/options.nix index 333a8cc3..3820efe6 100644 --- a/shared/oci-containers/options.nix +++ b/shared/oci-containers/options.nix @@ -6,14 +6,14 @@ let host = mkOption { type = types.int; description = mdDoc '' - Host port (on 127.0.0.1) to expose the inner port on. + Host port (on 127.0.0.1) to expose the container port on. ''; }; inner = mkOption { type = types.int; description = mdDoc '' - Container port. + The container port to expose to the hosti. ''; }; }; @@ -23,10 +23,13 @@ let type = types.nullOr types.str; default = null; description = mdDoc '' - Name of the volume. This creates a bind-mount to - `''${volumeBaseDir}/''${volumeSubDir}/''${name}`. + Name of the volume. This is equivalent to: - Exactly one of this or `''${host}` must be specified. + ```nix + host = "''${volumeBaseDir}/''${volumeSubDir}/''${name}"; + ``` + + This option c.logonflicts with `''${host}`. ''; }; @@ -36,7 +39,7 @@ let description = mdDoc '' Directory on the host to bind-mount into the container. - Exactly one of this or `''${name}` must be specified. + This option conflicts with `''${name}`. ''; }; @@ -54,7 +57,7 @@ let type = types.bool; default = true; description = mdDoc '' - Whether to start the container automatically on boot. + Start the container automatically on boot. ''; }; @@ -69,8 +72,10 @@ let dependsOn = mkOption { type = types.listOf types.str; default = [ ]; + example = [ "concourse-db" ]; description = mdDoc '' - Other containers that this one depends on. + Other containers that this one depends on, in `''${pod}-''${name}` + format. ''; }; @@ -151,8 +156,7 @@ let type = types.bool; default = true; description = mdDoc '' - Whether to pull the container image when starting (useful for `:latest` - images). + Pull the container image when starting (useful for `:latest` images). ''; }; }; diff --git a/shared/options.nix b/shared/options.nix index 68aefc71..f86b4fda 100644 --- a/shared/options.nix +++ b/shared/options.nix @@ -8,7 +8,13 @@ with lib; type = types.nullOr types.str; default = null; description = mdDoc '' - File containing IPs to block. + File containing IPs to block. This is of the form: + + ```text + ip-address # comment + ip-address # comment + ... + ``` ''; }; }; diff --git a/shared/pleroma/options.nix b/shared/pleroma/options.nix index 61bb0eab..9c5bddb1 100644 --- a/shared/pleroma/options.nix +++ b/shared/pleroma/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the Pleroma service. + Enable the [Pleroma](https://pleroma.social/) service. ''; }; @@ -40,7 +40,7 @@ with lib; type = types.nullOr types.path; default = null; description = mdDoc '' - Path to the favicon file. + File to use for the favicon. ''; }; @@ -73,14 +73,14 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Whether to allow new users to sign up. + Allow new users to sign up. ''; }; secretsFile = mkOption { type = types.str; description = mdDoc '' - Path to the secret configuration file. + File containing secret configuration. See the Pleroma documentation for what this needs to contain. ''; diff --git a/shared/resolved/options.nix b/shared/resolved/options.nix index ecd9c8a9..ae9a07db 100644 --- a/shared/resolved/options.nix +++ b/shared/resolved/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the resolved service. + Enable the [resolved](https://github.com/barrucadu/resolved) service. ''; }; diff --git a/shared/rtorrent/options.nix b/shared/rtorrent/options.nix index fd167610..e4c83a2d 100644 --- a/shared/rtorrent/options.nix +++ b/shared/rtorrent/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the rTorrent service. + Enable the [rTorrent](https://github.com/rakshasa/rtorrent) service. ''; }; @@ -74,14 +74,14 @@ with lib; type = types.bool; default = true; description = mdDoc '' - Enable the [flood](https://flood.js.org/) web UI. + Enable the [Flood](https://flood.js.org/) web UI. ''; }; port = mkOption { type = types.int; default = 45904; description = mdDoc '' - Port (on 127.0.0.1) to expose the flood service on. + Port (on 127.0.0.1) to expose Flood on. ''; }; }; diff --git a/shared/umami/options.nix b/shared/umami/options.nix index e1b5f707..cc7c8608 100644 --- a/shared/umami/options.nix +++ b/shared/umami/options.nix @@ -8,7 +8,7 @@ with lib; type = types.bool; default = false; description = mdDoc '' - Enable the umami service. + Enable the [umami](https://umami.is/) service. ''; }; @@ -39,8 +39,11 @@ with lib; environmentFile = mkOption { type = types.str; description = mdDoc '' - Environment file to be pased to the container. This needs to contain a - `HASH_SALT`. + Environment file to pass secrets into the service. This is of the form: + + ```text + HASH_SALT="..." + ``` ''; }; };