diff --git a/README.md b/README.md index c2e5251..4f11401 100644 --- a/README.md +++ b/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 diff --git a/docs/tutorials/deployprod.md b/docs/tutorials/deployprod.md new file mode 100644 index 0000000..6ed8173 --- /dev/null +++ b/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 +``` diff --git a/docs/tutorials/deploystaging.md b/docs/tutorials/deploystaging.md new file mode 100644 index 0000000..24f1e95 --- /dev/null +++ b/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. diff --git a/docs/tutorials/integrationtests.md b/docs/tutorials/integrationtests.md index a017cfb..61c62c7 100644 --- a/docs/tutorials/integrationtests.md +++ b/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: diff --git a/docs/tutorials/unittests.md b/docs/tutorials/unittests.md index fbf88ac..244cea9 100644 --- a/docs/tutorials/unittests.md +++ b/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 +```