This is a project that contains NixOS configurations for my machines.
The project uses flake-parts and import-tree to import all files under
./src as flake modules and make the flake.
Most flake modules under ./src define either a nixosModule or a homeModule
or both. Some of the modules define glue code for various tools that I started
relying on over the years which include but are not limited to:
The project uses the just command runner for running commands and nushell for running more complicated commands on my host machines. Both expect to be ran from inside the default development shell.
The project uses nix-unit for unit testing and
self.lib.test.mkTest (a wrapper over pkgs.testers.runNixOSTest)
for NixOS VM testing. An example of how to write tests can be found in the
library test file.
When adding test code (e2e or unit tests), commit the changes after tests pass
successfully using Conventional Commits format (e.g.,
test(module-name): add e2e test for critical-openssh).
If you can't get past some wall and you appear to be stuck for a long time and keep using very long timeouts and such it is okay to quit and let me take over and fix issues.
Use machine for the test node name and ensure test commands match this name
(e.g., machine.succeed()).
When writing e2e tests for modules that use dot.* options (e.g.,
dot.hardware.network.enable), you must mock these options in the test's
nodes.<name>.options attribute since they are defined in other modules which
are not imported by default.
For modules using external dependencies like sops-nix and cryl, import
their modules (e.g., self.nixosModules.cryl) and mock required
options. You generally don't need to set up actual secrets - the module will
configure secret paths automatically based on dot.host.user.
When verifying that a specific package or kernel version is being used, prefer
"canonical" paths over direct nix store searches. For example, use
readlink /run/booted-system/kernel to check the kernel instead of
find /nix/store -name '*kernel*'. Nix store paths are implementation details
and may change; canonical paths like symlinks in /run/booted-system/, /etc,
or service status checks are more stable and maintainable.
Always assign static IP addresses explicitly for all test nodes when testing
networking-related functionality and use addresses above at least 8 in the
prefix to prevent collisions with DHCP addresses (ie. DHCP sets up 192.168.1.1
and you set up 192.168.1.8). Relying on DHCP or default addressing can lead to
IP conflicts (e.g., multiple nodes getting the same IP address) which will cause
tests to fail in confusing ways. Use explicit
networking.interfaces.*.ipv4.addresses configurations for each node in
multi-node tests.
Test script host names are equal to networking.hostName in their config and if
that option is not set it will be set by the tester to the node name.
Unit test attrset leaves must have expr and expected args and their key must
start with test
Please read all the files mentioned in this file inside this repository - especially the justfile.
Always first check the justfile for available recipes before running any commands.
Nix flakes only see git-tracked files. When adding new test files or modules,
you must git add them before Nix can evaluate them. This is a common source of
"attribute not found" errors when adding new tests.
IMPORTANT: Never execute or run anything related to cryl or secret management tools. This includes:
- Do not run
crylcommands or import and execute its generators/importers - Do not generate, rotate, or export real certificates or keys
- Do not access or modify production Vault, SOPS, or Age keys
- Only mock the
cryl.*option schema for NixOS module compatibility when testing - Mock
sops.secretswith dummy paths and test data only when testing
These tools manage sensitive production credentials. Tests should only verify module configuration and service behavior using mock/test data, never interact with real secret infrastructure.