Add a README

etc/nixos/README.md

@@ -0,0 +1,56 @@
+# tlater.net server configuration
+
+This is the NixOS configuration for [tlater.net](https://tlater.net/).
+
+## Testing
+
+### Building
+
+To test locally in a VM, [nix](https://nixos.org/nix/) is
+required. Using a properly-configured nix, a qemu-based VM running the
+server can be created by first applying the following patch to disable
+hardware-specific configuration:
+
+```patch
+diff --git a/etc/nixos/configuration.nix b/etc/nixos/configuration.nix
+index 387113d..aabee88 100644
+--- a/etc/nixos/configuration.nix
++++ b/etc/nixos/configuration.nix
+@@ -2,8 +2,8 @@
+
+ {
+   imports = [
+-    ./hardware-configuration.nix
+-    ./linode.nix
++    # ./hardware-configuration.nix
++    # ./linode.nix
+   ];
+
+   networking = {
+```
+
+Then building the VM with:
+
+```
+nix-build '<nixpkgs/nixos>' -A vm -k -I nixos-config=./configuration.nix
+```
+
+### Running
+
+To invoke the VM, use:
+
+```
+QEMU_NET_OPTS="hostfwd=tcp::2222-:2222,hostfwd=tcp::8000-:80" ./result/bin/run-tlater.net-vm
+```
+
+This will set up a qemu VM with ports 2222 linked to the ssh port, and
+8000 to the http port. If other ports are required, adjust the
+environment variable (notably, ssl is provided by the image, although
+it should not work since it is unlikely that letsencrypt will supply
+any certificates).
+
+Note that other environment variables are available (such as one for
+disabling the qt GUI, probably handy for eventual CI). They are listed
+under "Building a service as a VM (for testing)"
+[here](https://nixos.wiki/wiki/Cheatsheet) (not linked since the page
+isn't set up very nicely).