modules: add commentary

31 files changed, 139 insertions, 0 deletions

diff --git a/modules/containers/freshrss/default.nix b/modules/containers/freshrss/default.nix
index 7d2e5eb..cb3193a 100644
--- a/modules/containers/freshrss/default.nix
+++ b/modules/containers/freshrss/default.nix
@@ -1,3 +1,7 @@
+# modules/containers/freshrss/default.nix
+#
+# An RSS reader and news aggregator.
+
 {
   config,
   lib,
diff --git a/modules/containers/jellyfin/default.nix b/modules/containers/jellyfin/default.nix
index aa0d4b1..3e45f43 100644
--- a/modules/containers/jellyfin/default.nix
+++ b/modules/containers/jellyfin/default.nix
@@ -1,3 +1,7 @@
+# modules/containers/jellyfin/default.nix
+#
+# Self-hosted Netflix.
+
 {
   config,
   lib,
diff --git a/modules/containers/lubelogger/default.nix b/modules/containers/lubelogger/default.nix
index c7ca98f..9c9424b 100644
--- a/modules/containers/lubelogger/default.nix
+++ b/modules/containers/lubelogger/default.nix
@@ -1,3 +1,7 @@
+# modules/profiles/lubelogger/default.nix
+#
+# Vehicle maintenance and fuel mileage tracker.
+
 {
   config,
   lib,
diff --git a/modules/containers/pinchflat/default.nix b/modules/containers/pinchflat/default.nix
index 6b5df23..e92cf44 100644
--- a/modules/containers/pinchflat/default.nix
+++ b/modules/containers/pinchflat/default.nix
@@ -1,3 +1,7 @@
+# modules/containers/pinchflat/default.nix
+#
+# For archiving and auto-downloading YouTube videos.
+
 {
   config,
   lib,
diff --git a/modules/containers/vaultwarden/default.nix b/modules/containers/vaultwarden/default.nix
index c04d679..92955c4 100644
--- a/modules/containers/vaultwarden/default.nix
+++ b/modules/containers/vaultwarden/default.nix
@@ -1,3 +1,7 @@
+# modules/containers/vaultwarden/default.nix
+#
+# The Bitwarden compatible password management server.
+
 {
   config,
   lib,
diff --git a/modules/containers/watchtower/default.nix b/modules/containers/watchtower/default.nix
index b7644ec..4fa0706 100644
--- a/modules/containers/watchtower/default.nix
+++ b/modules/containers/watchtower/default.nix
@@ -1,3 +1,7 @@
+# modules/containers/watchtower/default.nix
+#
+# I don't want to login and manually update my containers.
+
 {
   config,
   lib,
diff --git a/modules/customs/cgit/default.nix b/modules/customs/cgit/default.nix
index 6332044..7a20e9a 100644
--- a/modules/customs/cgit/default.nix
+++ b/modules/customs/cgit/default.nix
@@ -1,3 +1,10 @@
+# modules/customs/cgit/default.nix
+#
+# A web frontend for self-hosted git repositories. This module also creates a
+# git user for managing repositories on the git server.
+#
+# TODO: Fix syntax highlighting.
+
 {
   config,
   lib,
diff --git a/modules/default.nix b/modules/default.nix
index 6bf0abf..87a0634 100644
--- a/modules/default.nix
+++ b/modules/default.nix
@@ -1,3 +1,8 @@
+# modules/default.nix
+#
+# Helper functions for declaring system configurations and deployment nodes in
+# the root `flake.nix'.
+
 { inputs }:
 let
   mkModules = modules: builtins.map (module: "${inputs.self}/modules/${module}") modules;
diff --git a/modules/profiles/common/default.nix b/modules/profiles/common/default.nix
index 29c74e9..36c0b45 100644
--- a/modules/profiles/common/default.nix
+++ b/modules/profiles/common/default.nix
@@ -1,3 +1,7 @@
+# modules/profiles/common/default.nix
+#
+# Configuration and tweaks that should be included in *every* system.
+
 {
   inputs,
   config,
diff --git a/modules/profiles/fstrim/default.nix b/modules/profiles/fstrim/default.nix
index c49c570..ed9eb23 100644
--- a/modules/profiles/fstrim/default.nix
+++ b/modules/profiles/fstrim/default.nix
@@ -1,3 +1,7 @@
+# modules/profiles/fstrim/default.nix
+#
+# Routinely discard unused blocks in the filesystem on supported SSDs.
+
 {
   services.fstrim = {
     enable = true;
diff --git a/modules/profiles/libvirtd/default.nix b/modules/profiles/libvirtd/default.nix
index 6802938..bd4b7af 100644
--- a/modules/profiles/libvirtd/default.nix
+++ b/modules/profiles/libvirtd/default.nix
@@ -1,3 +1,7 @@
+# modules/profiles/libvirtd/default.nix
+#
+# Enable the libvirt virtualization management system.
+
 {
   config,
   ...
diff --git a/modules/profiles/nvidia/default.nix b/modules/profiles/nvidia/default.nix
index 30c7d0c..2decd36 100644
--- a/modules/profiles/nvidia/default.nix
+++ b/modules/profiles/nvidia/default.nix
@@ -1,3 +1,7 @@
+# modules/profiles/nvidia/default.nix
+#
+# Drivers for NVIDIA cards.
+
 {
   config,
   ...
diff --git a/modules/profiles/podman/default.nix b/modules/profiles/podman/default.nix
index 267bc00..ad47257 100644
--- a/modules/profiles/podman/default.nix
+++ b/modules/profiles/podman/default.nix
@@ -1,3 +1,8 @@
+# modules/profiles/podman/default.nix
+#
+# Podman is my preferred OCI container backend. It has the added bonus of
+# supporting building and starting containers via systemd.
+
 {
   virtualisation = {
     containers.enable = true;
diff --git a/modules/profiles/steam/default.nix b/modules/profiles/steam/default.nix
index a661434..a7ed2eb 100644
--- a/modules/profiles/steam/default.nix
+++ b/modules/profiles/steam/default.nix
@@ -1,3 +1,7 @@
+# modules/profiles/steam/default.nix
+#
+# For the occasional gaming session with friends.
+
 {
   programs.steam = {
     enable = true;
diff --git a/modules/profiles/upgrade/default.nix b/modules/profiles/upgrade/default.nix
index bde99d7..e91d0ba 100644
--- a/modules/profiles/upgrade/default.nix
+++ b/modules/profiles/upgrade/default.nix
@@ -1,3 +1,8 @@
+# modules/profiles/upgrade/default.nix
+#
+# Weekly package upgrades to keep select systems up to date. A service also
+# reports server events to notify me when a system updates or restarts.
+
 {
   inputs,
   config,
diff --git a/modules/profiles/vpn/default.nix b/modules/profiles/vpn/default.nix
index e3fc316..55d0c38 100644
--- a/modules/profiles/vpn/default.nix
+++ b/modules/profiles/vpn/default.nix
@@ -1,3 +1,8 @@
+# modules/profiles/vpn/default.nix
+#
+# Sometimes I'm on scary public networks, and I don't like other people
+# sniffing my network packets.
+
 {
   pkgs,
   ...
diff --git a/modules/profiles/wireguard/default.nix b/modules/profiles/wireguard/default.nix
index ef0a6b2..4e04604 100644
--- a/modules/profiles/wireguard/default.nix
+++ b/modules/profiles/wireguard/default.nix
@@ -1,3 +1,9 @@
+# modules/profiles/wireguard/default.nix
+#
+# Although my current ISP doesn't plague me with CGNAT, I use IPv6rs with
+# wireguard to host services from home without exposing ports on my router's
+# firewall.
+
 let
   listenPort = 51820;
 in
diff --git a/modules/profiles/wireshark/default.nix b/modules/profiles/wireshark/default.nix
index 1312188..31a58cb 100644
--- a/modules/profiles/wireshark/default.nix
+++ b/modules/profiles/wireshark/default.nix
@@ -1,3 +1,7 @@
+# modules/profiles/wireshark/default.nix
+#
+# For the occasional packet sniffing and network troubleshooting.
+
 {
   config,
   pkgs,
diff --git a/modules/profiles/xorg/default.nix b/modules/profiles/xorg/default.nix
index 0917fa9..703d70e 100644
--- a/modules/profiles/xorg/default.nix
+++ b/modules/profiles/xorg/default.nix
@@ -1,3 +1,8 @@
+# modules/profiles/xorg/default.nix
+#
+# Sure X11 is "old", but xmonad doesn't yet have xorg support. I've got my eyes
+# on https://github.com/YaLTeR/niri though.
+
 {
   pkgs,
   ...
diff --git a/modules/profiles/zfs/default.nix b/modules/profiles/zfs/default.nix
index f79e91c..9a5e0a2 100644
--- a/modules/profiles/zfs/default.nix
+++ b/modules/profiles/zfs/default.nix
@@ -1,3 +1,8 @@
+# modules/profiles/zfs/default.nix
+#
+# Enabling the ZFS kernel module and configuring notifications for scrub
+# results, which are run monthly.
+
 {
   lib,
   pkgs,
diff --git a/modules/profiles/zsa/default.nix b/modules/profiles/zsa/default.nix
index d07753f..e02ee88 100644
--- a/modules/profiles/zsa/default.nix
+++ b/modules/profiles/zsa/default.nix
@@ -1,3 +1,8 @@
+# modules/profiles/zsa/default.nix
+#
+# To avoid wrist pain and mitigate the chances of RSI, I use a split keyboard at
+# home. This provides the udev rules and a utility for flashing custom firmware.
+
 {
   pkgs,
   ...
diff --git a/modules/scripts/pushover/default.nix b/modules/scripts/pushover/default.nix
index 979e96b..b67771c 100644
--- a/modules/scripts/pushover/default.nix
+++ b/modules/scripts/pushover/default.nix
@@ -1,3 +1,7 @@
+# modules/scripts/pushover/default.nix
+#
+# Send notifications via the pushover API.
+
 {
   inputs,
   config,
diff --git a/modules/scripts/zquota/default.nix b/modules/scripts/zquota/default.nix
index a4262eb..5a0f249 100644
--- a/modules/scripts/zquota/default.nix
+++ b/modules/scripts/zquota/default.nix
@@ -1,3 +1,7 @@
+# modules/scripts/zquota/default.nix
+#
+# Monitor ZFS dataset disk usage.
+
 {
   config,
   lib,
diff --git a/modules/services/dns/default.nix b/modules/services/dns/default.nix
index a08ed6f..fb2d971 100644
--- a/modules/services/dns/default.nix
+++ b/modules/services/dns/default.nix
@@ -1,3 +1,7 @@
+# modules/services/dns/default.nix
+#
+# It's not DNS. There's no way it's DNS. It was DNS.
+
 {
   config,
   lib,
diff --git a/modules/services/fediverse/default.nix b/modules/services/fediverse/default.nix
index b67cdcc..b6e4b23 100644
--- a/modules/services/fediverse/default.nix
+++ b/modules/services/fediverse/default.nix
@@ -1,3 +1,8 @@
+# modules/services/fediverse/default.nix
+#
+# A portmanteau of "federation" and "universe". A lightweight instance for
+# participating in decentralized social media.
+
 {
   config,
   lib,
diff --git a/modules/services/matrix/default.nix b/modules/services/matrix/default.nix
index 0cfa56b..d8b8c28 100644
--- a/modules/services/matrix/default.nix
+++ b/modules/services/matrix/default.nix
@@ -1,3 +1,7 @@
+# modules/services/matrix/default.nix
+#
+# Secure, decentralized communication.
+
 {
   config,
   lib,
diff --git a/modules/services/searx/default.nix b/modules/services/searx/default.nix
index f7c00fb..e50e396 100644
--- a/modules/services/searx/default.nix
+++ b/modules/services/searx/default.nix
@@ -1,3 +1,7 @@
+# modules/services/searx/default.nix
+#
+# A metasearch engine and results aggregator.
+
 {
   config,
   lib,
diff --git a/modules/services/ssh/default.nix b/modules/services/ssh/default.nix
index 6f507cb..4ad87f1 100644
--- a/modules/services/ssh/default.nix
+++ b/modules/services/ssh/default.nix
@@ -1,3 +1,9 @@
+# modules/services/ssh/default.nix
+#
+# Configuration for secure remote access. I mainly use `mosh' for remoting into
+# servers, as it provides a smoother experience for boxes hosted halfway around
+# the world.
+
 {
   config,
   lib,
diff --git a/modules/services/website/default.nix b/modules/services/website/default.nix
index 425b69c..98f676a 100644
--- a/modules/services/website/default.nix
+++ b/modules/services/website/default.nix
@@ -1,3 +1,7 @@
+# modules/services/website/default.nix
+#
+# For hosting my personal site/blog and delegating traffic to my matrix server.
+
 {
   config,
   lib,
diff --git a/modules/services/xonotic/default.nix b/modules/services/xonotic/default.nix
index 33d45e2..9793380 100644
--- a/modules/services/xonotic/default.nix
+++ b/modules/services/xonotic/default.nix
@@ -1,3 +1,7 @@
+# modules/services/xonotic/default.nix
+#
+# This game is seriously addictive.
+
 {
   config,
   lib,
diff --git a/modules/users/default.nix b/modules/users/default.nix
index c5e675b..765bb1a 100644
--- a/modules/users/default.nix
+++ b/modules/users/default.nix
@@ -1,3 +1,7 @@
+# modules/users/default.nix
+#
+# Users to create on the system.
+
 {
   pkgs,
   ...