Comments & Readme

README.md

@@ -29,7 +29,16 @@ Repository structure:
   Age-encrypted secrets managed and deployed via agenix.
 
 - **var/**
-  Shared constants and values used across the configuration.
+  Shared data used across the configuration. `hosts.nix` is the single source
+  of truth for per-host data (SSH keys, WireGuard config). Adding a new host
+  means adding an entry there and running `bin/gen-syncthing-cert`.
+
+## Network topology
+
+WireGuard overlay network (onet, 10.10.11.0/24). Roam is the
+hub and the only publicly reachable node; desktops peer with roam only.
+Roam also runs a Mullvad WireGuard tunnel used as an egress for the torrent
+container configured in table 1000.
 
 ## TODO
 

host/roam/networking.nix

@@ -1,3 +1,5 @@
+# Roam has two WireGuard interfaces: wg0 (onet hub) and mullvad. Outgoing
+# container traffic is routed through mullvad via routing table 1000.
 {
   var,
   config,
@@ -7,7 +9,6 @@
 let
   wireguard-port = 51820;
 in
-
 {
   age.secrets.mullvad-vpn-key = {
     file = secrets.roam."mullvad-vpn-key.age";

mod/nginx.nix

@@ -1,3 +1,5 @@
+# Defines the `privateVirtualHosts` option: nginx vhosts served only on the
+# onet WireGuard interface using the internal TLS cert.
 {
   lib,
   options,

var/hosts.nix

@@ -1,3 +1,5 @@
+# Single source of truth for per-host data. Adding a host here (and running
+# bin/gen-syncthing-cert) wires it into all configs.
 {
   servers = {
     roam = {