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
+        ];
+      };
+  };
+}
+```