From fca1606f5aeb02719ed849080e1103e12ecd39ba Mon Sep 17 00:00:00 2001
From: Tristan Maat <tristan.maat@codethink.co.uk>
Date: Tue, 26 Nov 2019 23:19:19 +0000
Subject: [PATCH] Add a README

---
 etc/nixos/README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 etc/nixos/README.md

diff --git a/etc/nixos/README.md b/etc/nixos/README.md
new file mode 100644
index 0000000..e53ef8c
--- /dev/null
+++ b/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).