de-clutter the readme

README.md

@@ -112,104 +112,15 @@ Please see the [integration tests](/tests/integration) for examples.
 The workflow is the following:
 1. make a change,
 2. add or modify tests,
-3. run the tests,
-4. deploy to staging environment
-5. and deploy to production environment.
+3. run the [unit tests](/docs/tutorials/unittests.md) and [integration tests](/docs/tutorials/integrationtests.md),
+4. deploy to [staging environment](/docs/tutorials/deploystaging.md)
+5. and deploy to [production environment](/docs/tutorials/deployprod.md).
 
 The first two bullets are very general so I can't realistically
 enumerate all possibilities. I'll possibly provide examples in a
 following update.
 
-The remaining three are explained in the following subsections.
-
-### Run the tests
-
-For unit tests, do:
-
-```bash
-nix-instantiate --eval --strict . -A tests.unit
-```
-
-If all tests pass, you'll see the following output:
-
-```
-{ }
-```
-
-Otherwise, you'll see one attribute for each failing test. For example, you can dig into the first failing haproxy test with:
-
-```
-nix-instantiate --eval --strict . -A tests.unit.haproxy.0
-```
-
-To run integration tests, do:
-
-```bash
-nix-build -A tests.unit.all
-```
-
-### Deploy to staging environment
-
-Instead of deploying to prod machines, you'll deploy to VMs running on
-your computer with Virtualbox. This is tremendously helpful for
-testing.
-
-```bash
-export NIXOPS_DEPLOYMENT=vboxtest
-export DISNIXOS_USE_NIXOPS=1
-
-nixops create ./network-virtualbox.nix -d vboxtest
-
-nixops deploy --option extra-builtins-file $(pwd)/pkgs/extra-builtins.nix
-nixops reboot
-
-disnixos-env -s services.nix -n network-virtualbox.nix -d distribution.nix
-```
-
-It's okay if the `nixops deploy` command fails to activate the new
-configuration on first run because of the `virtualbox.service`. If
-that happens, continue with the `nixops reboot` command. The service
-will activate itself after the reboot.
-
-Rebooting after deploying is anyway needed for systemd to pickup the
-`/etc/systemd-mutable` path through the `SYSTEMD_UNIT_PATH`
-environment variable.
-
-The `extra-builtins-file` allows us to use password store as the
-secrets manager. You'll probably see errors about missing passwords
-when running this for the first time. To fix those, generate the
-password with `pass`.
-
-#### Handle host reboot
-
-After restarting the computer running the VMs, do `nixops start` and
-continue from the `nixops deploy ...` step.
-
-#### Cleanup
-
-To start from scratch, run `nixops destroy` and start at the `nixops
-deploy ...` step. This can be useful after fiddling with creating
-directories. You could do this on prod too but... it's probably not a
-good idea.
-
-Also, you'll need to add the `--no-upgrade` option when running
-`disnixos-env` the first time. Otherwise, disnix will try to
-deactivate services but since the machine is clean, it will fail to
-deactivate the services.
-
-### Deploy to prod
-
-```bash
-export NIXOPS_DEPLOYMENT=prod
-export DISNIXOS_USE_NIXOPS=1
-
-nixops create ./network-prod.nix -d prod
-
-nixops deploy --option extra-builtins-file $(pwd)/pkgs/extra-builtins.nix
-nixops reboot
-
-disnixos-env -s services.nix -n network-prod.nix -d distribution.nix
-```
+The following three are explained in the linked documents.
 
 ## Useful commands
 

docs/tutorials/deployprod.md

@@ -0,0 +1,17 @@
+### Deploy to prod
+
+Please read the [deploy to staging](/deploystaging.md) first as all
+commands are very similar. I only show a summary of the commands with
+staging variables replaced by prod ones.
+
+```bash
+export NIXOPS_DEPLOYMENT=prod
+export DISNIXOS_USE_NIXOPS=1
+
+nixops create ./network-prod.nix -d prod
+
+nixops deploy --option extra-builtins-file $(pwd)/pkgs/extra-builtins.nix
+nixops reboot
+
+disnixos-env -s services.nix -n network-prod.nix -d distribution.nix
+```

docs/tutorials/deploystaging.md

@@ -0,0 +1,48 @@
+# Deploy to staging environment
+
+Instead of deploying to prod machines, you'll deploy to VMs running on
+your computer with Virtualbox. This is tremendously helpful for
+testing.
+
+```bash
+export NIXOPS_DEPLOYMENT=vboxtest
+export DISNIXOS_USE_NIXOPS=1
+
+nixops create ./network-virtualbox.nix -d vboxtest
+
+nixops deploy --option extra-builtins-file $(pwd)/pkgs/extra-builtins.nix
+nixops reboot
+
+disnixos-env -s services.nix -n network-virtualbox.nix -d distribution.nix
+```
+
+It's okay if the `nixops deploy` command fails to activate the new
+configuration on first run because of the `virtualbox.service`. If
+that happens, continue with the `nixops reboot` command. The service
+will activate itself after the reboot.
+
+Rebooting after deploying is anyway needed for systemd to pickup the
+`/etc/systemd-mutable` path through the `SYSTEMD_UNIT_PATH`
+environment variable.
+
+The `extra-builtins-file` allows us to use password store as the
+secrets manager. You'll probably see errors about missing passwords
+when running this for the first time. To fix those, generate the
+password with `pass`.
+
+## Handle host reboot
+
+After restarting the computer running the VMs, do `nixops start` and
+continue from the `nixops deploy ...` step.
+
+## Cleanup
+
+To start from scratch, run `nixops destroy` and start at the `nixops
+deploy ...` step. This can be useful after fiddling with creating
+directories. You could do this on prod too but... it's probably not a
+good idea.
+
+Also, you'll need to add the `--no-upgrade` option when running
+`disnixos-env` the first time. Otherwise, disnix will try to
+deactivate services but since the machine is clean, it will fail to
+deactivate the services.

docs/tutorials/integrationtests.md

@@ -8,7 +8,7 @@ You can find all integration tests under the [tests/integration](/tests/integrat
 ## Run integration tests
 
 ```console
-nix-build -A tests.integration.keycloak
+nix-build -A tests.integration.all
 ```
 
 To run the "simple" integration test for keycloak, execute:

docs/tutorials/unittests.md

@@ -4,3 +4,21 @@ Unit tests are used in Self Host Blocks to check that parsing
 configurations produce the expected result.
 
 You can find all unit tests under the [tests/unit](/tests/unit) directory.
+
+To run the units test, do:
+
+```bash
+nix-instantiate --eval --strict . -A tests.unit
+```
+
+If all tests pass, you'll see the following output:
+
+```
+{ }
+```
+
+Otherwise, you'll see one attribute for each failing test. For example, you can dig into the first failing haproxy test with:
+
+```
+nix-instantiate --eval --strict . -A tests.unit.haproxy.0
+```