Nix Configuration Patterns
Critical Rules
| Rule | Why |
|---|
Run update after changes | Nothing takes effect until rebuilt |
Run git add before nix flake check | Flakes only see git-tracked files |
Use lib.fakeHash for unknown hashes | Nix will tell you the real hash on build failure |
Common Mistakes
| Wrong | Right |
|---|
Running nix flake check on new files without git add | git add <file> first |
| Editing config and expecting immediate effect | Run update to rebuild |
| Guessing SHA256 hashes | Use lib.fakeHash, build, copy real hash from error |
| Adding package only to overlay | Also add to pkgs/default.nix |
Commands
update # Rebuild current system
nix flake check # Validate flake
nix build .#<package> # Build package
nix eval .#nixosConfigurations.<host>.config.<option> # Check config value
Package Pattern
# pkgs/<name>/default.nix
{ lib, stdenv, fetchFromGitHub, ... }:
stdenv.mkDerivation rec {
pname = "name";
version = "1.0.0";
src = fetchFromGitHub {
owner = "...";
repo = "...";
rev = "v${version}";
hash = "sha256-AAAA..."; # Use lib.fakeHash first, nix will tell you real hash
};
meta = with lib; {
description = "...";
license = licenses.mit;
platforms = platforms.all;
};
}
Then add to pkgs/default.nix and overlays/default.nix.
Home Manager Module Pattern
# home-manager/<app>/default.nix
{ pkgs, lib, ... }: {
home.packages = [ pkgs.app ];
# Or use programs.<app> if module exists
programs.app = {
enable = true;
settings = { ... };
};
}
Then import in home-manager/common.nix or platform-specific file.
Agenix Secret Pattern
# 1. Add to secrets/secrets.nix
"secrets/hosts/<host>/<name>.age".publicKeys = keys.<host>;
# 2. Declare in host config
age.secrets."<name>" = {
file = ../../secrets/hosts/<host>/<name>.age;
owner = "<service-user>";
mode = "0400";
};
# 3. Create the secret
agenix -e secrets/hosts/<host>/<name>.age
This Repo's Systems
| Host | Platform | Notes |
|---|
| ninuan | macOS | Primary dev, Aerospace WM |
| ultraviolet | NixOS | Headless server |
| bluedesert | NixOS | Headless server |
| echelon | NixOS | Headless server |
