The Scary Door for Non-Nix:ers

This README.md contains an overview of the Nix development and deployment strategy for The Scary Door. While it's of course easiest to use and follow on NixOS, everything detailed is possible and relevant on other distros, as long as you can install Nix, as well as QEMU and binfmt support for deployment.

Also, keep in mind that the source code itself is untouched despite this Nix transition; you can still develop, compile, and run it on other distros without Nix just as well as you could before. The only thing this move to Nix has strictly replaced is the tedious, manual deployment of The Scary Door that we had previously. Besides that, it's more of an optional package/build tool that can make your life easier if you embrace Nix, and will leave you alone if you don't. But mostly, it's an experiment on using Nix and NixOS for deployment.

flake.nix

Our entrypoint is the flake.nix file. It has two top-level values, inputs and outputs.

• inputs are our imports, the most important one being nixpkgs. This, along with the flake.lock file, can be thought of as our state.
• outputs are our… outputs. In our case, we export 5 things.

The 3 outputs below are outputs explicitly related to The Scary Door as an application. This flake.nix is the intended, idiomatic place for them.

• packages.default, which is the compiled binary of The Scary Door.
• devShells.default, which is a development shell containing relevant development tools and libraries.
• nixosModules.default, which is a NixOS module that makes it easy to install and manage The Scary Door on a NixOS system. So far, there is only a single enable option.

The 2 outputs below are more related to infrastructure and the deployment of The Scary Door. These would rather belong in a larger infrastructure flake.nix, with multiple other NixOS configurations and deploy nodes, akin to our current Terraform + Ansible new-infra, but for now at least, they sit here instead.

• nixosConfigurations.the-scary-door, which is a NixOS configuration that solely runs The Scary Door, intended for the Raspberry Pi 3B mounted above the sink next to Bosch.
• deploy.nodes.the-scary-door, which is a deploy-rs target machine which we want to deploy a NixOS configuration to.

Usage

You can enter the default temporary development shell using nix develop (this can be automated via direnv!). There, you have access to cargo, rustc, and rust-analyzer, as well as pkg-config and the pcsclite middleware. You can also build/run the default package with nix build and nix run (although for development, cargo build and cargo run in the development shell are significantly faster).

Also, you might need to enable the "experimental" nix commands and flakes. Either add --extra-experimental-features "nix-command flakes" to your command, create /etc/nix/nix.conf with these contents:

experimental-features = nix-command flakes

or add the following to your NixOS configuration:

nix.settings.experimental-features = "nix-command flakes";

Deployment

Deploying is done with the help of deploy-rs. While deploying is possible "natively" through the nixos-rebuild [switch/boot/test] --target-host [TARGET_HOST] command, deploy-rs streamlines the process by letting you declare deployment targets and their profiles in a flake.nix, allowing for easy multi-profile, multi-node deployments, in just a single short command.

Since our Raspberry Pi can barely handle compiling The Scary Door on its own, and would surely struggle with building the NixOS configuration (minimal as it may be), compiling the binary and building the configuration (profile) to be deployed are instead handled on your machine. Since our Raspberry Pi is aarch64, and you're likely on an x86_64 computer, This means that we have to do cross-compiling. The easiest way is with emulation of aarch64 through binfmt. On NixOS, add aarch64 to your emulated systems in your configuration:

boot.binfmt.emulatedSystems = ["aarch64"];

On other distros, look into installing QEMU for aarch64, enabling binfmt support, and registering aarch64 with binfmt.

(Currently, the compiling of The Scary Door is also done through emulation, rather than cross-compiling, which makes it very slow. This will be fixed Soon™!)

deploy-rs connects to the machine through SSH. Thus, you'll need to be able to connect to the machine over SSH. Currently, only my (hexfae/Arvid Öström) public key is authorized while I think about how this should be managed. Let me know if you want yours added, too!

Then, deploying can be done by running nix run nixpkgs#deploy-rs . (note the period, meaning "the current directory's flake.nix") to deploy all nodes (which is only one), or e.g. nix run nixpkgs#deploy-rs .#the-scary-door to deploy a single node. If everything goes well (the build succeeds, the activation succeeds, and the machine is still connectable after the activation), congratulations, you've just deployed The Scary Door. If anything went wrong, it will either rollback to the latest working generation, or simply not active the new configuration. If you wish to rollback manually, SSH into it and (as root) run nixos-rebuild switch --rollback.