Mike Dalrymple My NixOS Experiment

My NixOS Experiment

I experimented with NixOS as the base for a new Home Assistant server I’m building but ended up not using it in production because of issues with the documentation and general concerns around packaging.

Why NixOS?

NixOS is a Linux based operating system that uses a declarative approach to system configuration. Using the nix language along with nixpkgs you declare what your desired system configuration should be and Nix does the heavy lifting for you. I first heard about NixOS on the LINUX Unplugged Podcast and since I’m a fan of declarative configs, I thought I’d give it a try.


Over the course of a few evenings, I had NixOS configured and running on two ODROID H3 servers. The servers were successfully joining my Tailscale tailnet using a nix configured Wi-Fi connection. I was having so much fun, I even had a PR merged to correct a minor documentation error.

After a few weeks of intermittent attention, I had a minimally viable Home Assistant server running nix packages for Podman, Mosquitto, Prometheus, and Grafana with Home Assistant and Z-Wave JS containers running as systemd services under Podman.


My initial server configuration was the result of copying and pasting various bits and pieces of nix configurations I found online (most from the “unofficial” NixOS wiki). Before promoting my server to production, I wanted to better understand what configuration options were available for the packages I had installed. This is where things started to unravel.


I was unable to find a single, comprehensive source of information for the packages I was using. My primary resources were the NixOS Manual, NixOS Search (Packages and Options), and the NixOS Wiki. Using the Mosquitto MQTT broker package as an example, we end up with documentation in the following locations:

Meanwhile, the NixOS Manual doesn’t have documentation for the Grafana package. Instead, that package can be found on the NixOS wiki with package details and options only available through the search interface.

Further complicating matters, search engines are prioritizing GitHub sources rather than useful NixOS documentation. At the time of this writing, a Google Search for nixos mosquitto returns a NixOS test file from GitHub as the top result.

Developers would benefit from a single, search engine optimized, documentation site that aggregates all package details (latest version, options, examples) into a single interface similar to the Ansible Community Documentation site.


Using NixOS packages adds another step in the supply chain from the software provider to your deployment. As far as I could tell, for the packages I was using, none were being managed by the upstream software provider. This means another party (not necessarily associated with the project) is taking on the responsibility for packaging the software for NixOS.

When I started writing this post, the latest version of Grafana was 9.3.6 but the latest available NixOS package version was 9.3.1. I don’t know what (if any) significant changes there were between those versions, but I’m not certain how comfortable I would feel relying on NixOS if I really needed one of those point releases.

This isn’t a problem unique to NixOS, similar issues exist with other packaging systems like Snapd, Flatpak, and Debian packages. Package maintenance is a thankless task, and it’s unreasonable to expect same-day delivery of new software releases. However, if you’re maintaining critical infrastructure, you may want to have greater control of the software versions you’re deploying.

Baby Next Steps

The NixOS ecosystem seems large and varied as a newbie outsider. It was naive of me to jump in with the goal of deploying a production system relatively quickly. If I had it to do over again, I would focus on nix-shell and use that as a platform for learning more about Nix. That’s what I plan to do now as I move forward with NixOS in my development workflow. If that ends up being a success, I might come back to NixOS for production deployments.