Editing pass to make module docs consistent

shared/backups/default.nix

@@ -20,6 +20,11 @@
 #
 # Change the restore target by setting `$RESTORE_DIR`.
 #
+# **Alerts:**
+#
+# - A backup script terminates with an error.
+# - Uploading the backup to s3 fails.
+#
 # [Duplicity]: https://duplicity.gitlab.io/
 # [defined in the ops repo]: https://github.com/barrucadu/ops/blob/master/aws/backups.tf
 { config, lib, pkgs, ... }:

shared/bookdb/default.nix

@@ -4,11 +4,9 @@
 # bookdb 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.
+# **Backups:** the elasticsearch database and uploaded files.
 #
-# If the `erase-your-darlings` module is enabled, stores its data on the
-# persistent volume.
+# **Erase your darlings:** overrides the `dataDir`.
 #
 # [bookdb]: https://github.com/barrucadu/bookdb
 # [bookdb.barrucadu.co.uk]: https://bookdb.barrucadu.co.uk/

shared/bookmarks/default.nix

@@ -3,10 +3,7 @@
 #
 # bookmarks uses a containerised elasticsearch 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.
+# **Backups:** the elasticsearch database.
 #
 # [bookmarks]: https://github.com/barrucadu/bookmarks
 # [bookmarks.barrucadu.co.uk]: https://bookmarks.barrucadu.co.uk/

shared/concourse/default.nix

@@ -3,15 +3,11 @@
 #
 # Concourse uses a containerised postgres database.
 #
-# If the `backups` module is enabled, adds a script to backup the database.
+# Provides a grafana dashboard.
 #
-# If the `erase-your-darlings` module is enabled, stores its data on the
-# persistent volume.
-#
-# Enabling this module also provisions a [Grafana][] dashboard.
+# **Backups:** the postgres database.
 #
 # [Concourse CI]: https://concourse-ci.org/
-# [Grafana]: https://grafana.com/
 { config, lib, pkgs, ... }:
 
 with lib;

shared/default.nix

@@ -1,4 +1,8 @@
 # Common configuration enabled on all hosts.
+#
+# **Alerts:**
+#
+# - A zpool is in "degraded" status (alertmanager)
 { config, lib, pkgs, flakeInputs, ... }:
 
 with lib;

shared/erase-your-darlings/default.nix

@@ -69,7 +69,5 @@ in
     services.caddy.dataDir = "${toString cfg.persistDir}/var/lib/caddy";
     services.dockerRegistry.storagePath = "${toString cfg.persistDir}/var/lib/docker-registry";
     services.syncthing.dataDir = "${toString cfg.persistDir}/var/lib/syncthing";
-
-    nixfiles.oci-containers.volumeBaseDir = "${toString cfg.persistDir}/docker-volumes";
   };
 }

shared/foundryvtt/default.nix

@@ -2,15 +2,12 @@
 # software and needs to be downloaded after purchase.  This module doesn't
 # manage the FoundryVTT program files, only operating it.
 #
-# The downloaded FoundryVTT program files must be in
-# `{nixfiles.foundryvtt.dataDir}/bin`.
+# The downloaded FoundryVTT program files must be in `''${dataDir}/bin`.
 #
-# If the `backups` module is enabled, adds a script to backup the data files.
-# This requires briefly stopping the service, so don't schedule backups during
-# game time.
+# **Backups:** the data files - this requires briefly stopping the service, so
+# don't schedule backups during game time.
 #
-# If the `erase-your-darlings` module is enabled, stores its data on the
-# persistent volume.
+# **Erase your darlings:** overrides the `dataDir`.
 #
 # [FoundryVTT]: https://foundryvtt.com/
 { config, lib, pkgs, ... }:

shared/minecraft/default.nix

@@ -5,13 +5,12 @@
 # nixpkgs and only runs one server, whereas I want to run multiple modded
 # servers.
 #
-# The Minecraft server files must be in `{nixfiles.minecraft.dataDir}/{name}`.
+# The Minecraft server files must be in `''${dataDir}/{name}`.
 #
 # This module does not include a backup script.  Servers must be backed up
 # independently.
 #
-# If the `erase-your-darlings` module is enabled, stores its data on the
-# persistent volume.
+# **Erase your darlings:** overrides the `dataDir`.
 #
 # [Minecraft]: https://www.minecraft.net/en-us
 { config, lib, pkgs, ... }:

shared/oci-containers/default.nix

@@ -1,3 +1,7 @@
+# ```admonish note title="To do"
+# Run podman containers run as a non-root user.
+# ```
+#
 # An abstraction over running containers as systemd units, enforcing some good
 # practices:
 #
@@ -8,12 +12,9 @@
 # Switching between using docker or podman for the container runtime should be
 # totally transparent.
 #
-# If the `erase-your-darlings` module is enabled, stores volume bind-mounts on
-# the persistent volume.
+# **Erase your darlings:** overrides the `volumeBaseDir`.
 { config, lib, pkgs, ... }:
 
-# TODO: ensure podman containers run as a non-root user
-
 with lib;
 let
   mkPortDef = { host, inner }: "127.0.0.1:${toString host}:${toString inner}";
@@ -99,6 +100,7 @@ in
 {
   imports = [
     ./options.nix
+    ./erase-your-darlings.nix
   ];
 
   config = {

shared/oci-containers/erase-your-darlings.nix

@@ -0,0 +1,11 @@
+{ config, lib, ... }:
+
+with lib;
+let
+  eyd = config.nixfiles.eraseYourDarlings;
+in
+{
+  config = mkIf eyd.enable {
+    nixfiles.oci-containers.volumeBaseDir = "${toString eyd.persistDir}/docker-volumes";
+  };
+}

shared/pleroma/default.nix

@@ -2,11 +2,9 @@
 #
 # Pleroma uses a containerised postgres database.
 #
-# If the `backups` module is enabled, adds a script to backup the database and
-# uploaded files.
+# **Backups:** the postgres database, uploaded files, and custom emojis.
 #
-# If the `erase-your-darlings` module is enabled, stores its data on the
-# persistent volume.
+# **Erase your darlings:** transparently stores data on the persistent volume.
 #
 # [Pleroma]: https://pleroma.social/
 { config, lib, pkgs, ... }:

shared/resolved/default.nix

@@ -1,9 +1,8 @@
 # [resolved][] is a recursive DNS server for LAN DNS.
 #
-# Enabling this module also provisions a [Grafana][] dashboard.
+# Provides a grafana dashboard.
 #
 # [resolved]: https://github.com/barrucadu/resolved
-# [Grafana]: https://grafana.com/
 { config, lib, pkgs, ... }:
 
 with lib;

shared/rtorrent/default.nix

@@ -4,8 +4,8 @@
 # This module does not include a backup script.  Torrented files must be backed
 # up independently.
 #
-# If the `erase-your-darlings` module is enabled, stores the session data and
-# logs on the persistent volume.
+# **Erase your darlings:** transparently stores session data and logs on the
+# persistent volume.
 #
 # [rTorrent]: https://github.com/rakshasa/rtorrent
 { config, lib, pkgs, ... }:

shared/umami/default.nix

@@ -2,10 +2,7 @@
 #
 # umami 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.
+# **Backups:** the postgres database.
 #
 # [umami]: https://umami.is/
 { config, lib, pkgs, ... }: