1
0
Fork 0

de-clutter the readme

This commit is contained in:
ibizaman 2023-03-17 21:07:37 -07:00
parent e85c2e945e
commit 26293bb5a2
5 changed files with 88 additions and 94 deletions

View file

@ -112,104 +112,15 @@ Please see the [integration tests](/tests/integration) for examples.
The workflow is the following: The workflow is the following:
1. make a change, 1. make a change,
2. add or modify tests, 2. add or modify tests,
3. run the tests, 3. run the [unit tests](/docs/tutorials/unittests.md) and [integration tests](/docs/tutorials/integrationtests.md),
4. deploy to staging environment 4. deploy to [staging environment](/docs/tutorials/deploystaging.md)
5. and deploy to production environment. 5. and deploy to [production environment](/docs/tutorials/deployprod.md).
The first two bullets are very general so I can't realistically The first two bullets are very general so I can't realistically
enumerate all possibilities. I'll possibly provide examples in a enumerate all possibilities. I'll possibly provide examples in a
following update. following update.
The remaining three are explained in the following subsections. The following three are explained in the linked documents.
### 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
```
## Useful commands ## Useful commands

View file

@ -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
```

View file

@ -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.

View file

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

View file

@ -4,3 +4,21 @@ Unit tests are used in Self Host Blocks to check that parsing
configurations produce the expected result. configurations produce the expected result.
You can find all unit tests under the [tests/unit](/tests/unit) directory. 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
```