improve docs

README.md

@@ -1,2 +1,85 @@
 # birdsong
 
+A private WireGuard VPN.
+
+## Connecting a new host
+
+1. Generate a new WireGuard keypair with the `wg` binary (packaged on many distros as `wireguard-tools`.) [There are instructions on the Arch wiki.](https://wiki.archlinux.org/title/WireGuard#Key_generation)
+
+2. Add the host to `hosts.nix`, being sure to read the documentation carefully.
+
+3. For a NixOS host:
+    1. Install the NixOS module as described below.
+    2. Enable the `birdsong` service in your NixOS configuration:
+    ```nix
+    birdsong.peering = {
+        enable = true;
+        privateKeyFile = /path/to/wireguard/private.key;
+        # This is the bare minimum - check peering.nix for other options.
+        # In particular, quick fix for issues with NAT or dynamic public IPs:
+        # persistentKeepalive = 23
+    };
+    ```
+
+4. For a non-NixOS host:
+    1. TODO
+
+## Installing the NixOS module
+
+### With plain Nix fetching
+
+```nix
+{ config, lib, pkgs, ... }:
+{
+  imports = [
+    # ...
+
+    (let
+      birdsong = fetchgit {
+        url = "https://git.qenya.tel/qenya/birdsong";
+        hash = "sha256-pPrREPA7kJdfMXk0hJLbq6UGOiq+KtJo1LR4vC69vxM=";
+        rev = "04e5519bf363388debfafc31285851c7816d087a";
+        # This shows an example commit ID; update to the most recent and
+        # recalculate the hash
+      };
+      in import "${birdsong}/module.nix"
+    )
+  ];
+}
+```
+
+### With [npins](https://github.com/andir/npins)
+
+```sh
+$ npins add --name birdsong git --branch main "https://git.qenya.tel/qenya/birdsong.git"
+```
+
+```nix
+{ config, lib, pkgs, ... }:
+let sources = import ./npins;
+in {
+  imports = [
+    # ...
+    (import "${sources.birdsong}/module.nix")
+  ];
+}
+```
+
+### With flakes
+
+```nix
+{
+  inputs.birdsong.url = "git+https://git.qenya.tel/qenya/birdsong?ref=main"
+
+  outputs = { self, nixpkgs, birdsong, ... }: {
+      # Tweak as appropriate for your hostname, platform, architecture etc.
+      nixosConfigurations.your-box = nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux"
+        modules = [
+          # ...
+          birdsong.nixosModules.default
+        ];
+      };
+  };
+}
+```

hosts.nix

@@ -26,7 +26,8 @@ with lib;
               The special value `roaming` will not peer with other `roaming`
               hosts, but will still peer with `internet` hosts. This is to be
               used for portable devices like laptops that regularly move between
-              networks.
+              networks. Also use this for non-NixOS devices that can't use the
+              NixOS module and therefore only peer with the subnet router.
             '';
             type = types.str;
           };
@@ -48,12 +49,22 @@ with lib;
           };
           ipv4 = mkOption {
             example = "10.127.1.1";
-            description = "IPv4 address of this peer within the network";
+            description = ''
+              IPv4 address of this peer within the network.
+
+              We are currently using the range 10.127.0.0/16, divided into /24
+              subnets. Please try to keep this consistent.
+            '';
             type = types.str;
           };
           ipv6 = mkOption {
             example = "fd70:81ca:0f8f:1::1";
-            description = "IPv6 address of this peer within the network";
+            description = ''
+              IPv6 address of this peer within the network.
+
+              We are currently using the range fd70:81ca:0f8f::/48, divided
+              into /64 subnets. Please try to keep this consistent.
+            '';
             type = types.str;
           };
           port = mkOption {