Nix configuration is using this approach as its spirit guide: https://github.com/Baitinq/nixos-config
One should first make sure all changes are committed to the repo.
nix flake update
sudo nixos-rebuild switch --flake .
Substituters are set in configuration.nix (nix.settings). Nix tries them in priority order:
| Cache | Priority | Purpose |
|---|---|---|
https://cache.nixos.org |
40 | Upstream. |
http://mini-nas.forge.local:8770/public |
41 | Attic on mini-nas. mini-nas, thenixbeast and steamdeck push everything they build here (modules/attic-push). Paths expire 6 months after last access (server default). |
http://mini-nas.forge.local:8770/archive |
50 | Attic on mini-nas, garbage collection disabled (retention 0). For store paths that must never disappear, such as sources whose upstream was withdrawn. |
Hosts that import modules/attic-push queue each build from a post-build-hook, and a daemon pushes it, retrying for an hour if mini-nas is unreachable. Check it with journalctl -u queued-build-hook. mini-nas does the same, and mints its own token at boot.
The other hosts share one token, in modules/attic-push/secrets.yaml. Attic can't revoke a single token, only rotate the key that signs them all, so per-host tokens would buy nothing. To create or replace it:
- On mini-nas:
sudo atticd-atticadm make-token --sub workstations --validity 99y --pull public --push public sops modules/attic-push/secrets.yaml, and setattic: { push_token: <token> }.
If upstream deletes its source, a package can still build as long as its fixed-output paths (the src, plus things like cargoDeps/npmDeps) can be substituted by hash. Keep the old hash/cargoHash, and make sure those paths live in archive. Current contents:
- qbz 2.0.2 (
pkgs/qbz, removed from nixpkgs 2026-09-18 after the author withdrew it):/nix/store/2jfmb3dj1l1sc7pf6gca0vsczdkrikpi-source,/nix/store/ww0rw91wr6cgyjcpzg3zwr0vz8xikh30-qbz-2.0.2-vendor- Built output, with its full closure (pushed with
--ignore-upstream-cache-filter), so a known-good build survives even if a later nixpkgs breaks the build. Built 2026-10-02 against nixpkgsc59305b; it needs ~40 GB of RAM + swap to compile (seepkgs/qbz):/nix/store/9qhhlswxz79vfcgjnprjj09nacl4gwv5-qbz-2.0.2
- Built output, with its full closure (pushed with
To add paths (Attic server config lives in the mini-nas repo, modules/attic):
- Make sure the paths are local:
nix-store --realise <path>...(they're usually still on cache.nixos.org). - You need a token with push access to
archive. The everydaymini-nastoken in~/.config/attic/config.tomlcan't do this. Mint a short-lived one on mini-nas and log in under a separate name:sudo atticd-atticadm make-token --sub will --validity 1d --push archive --pull archive attic login mini-nas-admin http://mini-nas.forge.local:8770 <token>
- Push.
--ignore-upstream-cache-filteris required: the cache listscache.nixos.org-1as upstream, so without the flag Attic silently skips anything cache.nixos.org has signed.attic push --ignore-upstream-cache-filter mini-nas-admin:archive <path>...
- Verify:
nix path-info --sigs --store http://mini-nas.forge.local:8770/archive <path>...should list each path with anarchive:signature. - Record the paths in the list above, then remove the
[servers.mini-nas-admin]block from~/.config/attic/config.toml.
If a push fails:
- Times out after about 30 s, and atticd logs
Connection pool timed out: SQLite has no query statistics. It picksidx-chunk-state-holdersinstead ofidx-chunk-chunk-hash, and every chunk lookup scans about 1.5M rows. Fix it on mini-nas: stop atticd,sqlite3 /var/lib/private/atticd/server.dbconsole runANALYZE;, then start atticd again. First fixed 2026-09-21. - Fails with a fast 500, and atticd logs
database is locked, right after atticd restarts: atticd runs a GC pass on startup that holds the write lock. Wait untilserver.db-walstops growing, then retry.
The cache was created with attic cache create …:archive --public and attic cache configure …:archive --priority 50 --retention-period 0s. Its public key, archive:1X1f2tklkN82QbeLjMYnySG9zhP+fWJsBSjK9Y6tPrY=, is in trusted-public-keys.
https://nixos.wiki/wiki/Creating_a_NixOS_live_CD
- The configuration is already in
flake.nix nix build .#nixosConfigurations.iso.config.system.build.isoImage- The resulting image can be found in
result/iso/ - Write to the USB drive (assuming
/dev/sdbin this example - double check!):sudo dd if=results/iso/<distro_name>.iso of=/dev/<sdb> status=progress
Reference: https://wiki.nixos.org/wiki/ZFS
- Create a NixOS liveUSB (instructions above)
- Generate a host SSH key:
TEMP_SSH=$(mktemp -d)
install -d -m755 "$TEMP_SSH/etc/ssh"
ssh-keygen -t ed25519 -N "" -f "$TEMP_SSH/etc/ssh/ssh_host_ed25519_key"
chmod 600 "$TEMP_SSH/etc/ssh/ssh_host_ed25519_key"
cat $TEMP_SSH/etc/ssh/ssh_host_ed25519_key.puband add that value to the.sops.yamlin this repo, constrain it to only caring about its own host secrets file, plus the shared ones under "Adding a host to the build network" below.sops updatekeysfor the file/host you'll be deploying to.- Optionally, do steps similar to the ones above - creating user SSH keys to be deployed onto the machine. Update the corresponding host secrets file with those keys, so they're deployed. Also add new entries for them to the
.sops.yamlbecause ideally the user can edit all other secrets files.
TEMP_USER_SSH=$(mktemp -d)
ssh-keygen -t ed25519 -f "$TEMP_USER_SSH/id_ed25519"
- Boot the target machine using the liveUSB.
- Change to
root:sudo su - Set a password:
passwd - Note the target machine's ip address:
ip addr - From a remote machine, SSH into the target machine, for running the following steps.
sudo gdisk /dev/nvme0n1- We'll need a boot partition (ESP), a swap partition, and a large partition for NixOS (the type will be "8300" "Linux filesystem"). (Presuming that the boot and swap partitions have already been set up.)
- Get the device IDs (ls /dev/disk/by-id/) and set them as variables like:
BOOT=/dev/disk/by-id/nvme-Samsung_SSD_990_PRO_4TB_S7KGNJ0X145827A-part1
SWAP=/dev/disk/by-id/nvme-Samsung_SSD_990_PRO_4TB_S7KGNJ0X145827A-part7
DISK=/dev/disk/by-id/nvme-Samsung_SSD_990_PRO_4TB_S7KGNJ0X145827A-part8
- Create the pool:
zpool create -o ashift=9 -o autotrim=on -O compression=zstd-9 -O mountpoint=none -O canmount=off -O xattr=sa -O acltype=posix -O dnodesize=auto -O atime=off -O normalization=formD rpool $DISK
- This SSD claims (
sudo fdisk -l) 512 bytes as its ideal sector size, so going withashift=9, even though12is the typical recommendation and often even13for SSDs. compression=zstd-9 7FAC: probably too much.on/lz4is a no-brainer.zstd-3is the default. Cranking up the compression ratio this high might bottleneck on the CPU, rather than bottle-necking on reading off the NVME SSD.dnodesize=autoatime=off: disable writing the "access time" for every file read.normalization=formD: something about using UTF-8 for filenames, and using the formD algorithm for comparison - which seems vaguely broadly compatible.
- Create filesystems:
zfs create -o canmount=noauto rpool/root
zfs create rpool/home
zfs create rpool/nix
zfs create rpool/var
- Mount those filesystems:
mount -o X-mount.mkdir -o zfsutil -t zfs rpool/root /mnt
mount -o X-mount.mkdir -o zfsutil -t zfs rpool/home /mnt/home
mount -o X-mount.mkdir -o zfsutil -t zfs rpool/nix /mnt/nix
mount -o X-mount.mkdir -o zfsutil -t zfs rpool/var /mnt/var
mount -o X-mount.mkdir $BOOT /mnt/boot
swapon $SWAP
- Deploy. In a separate terminal, on the remote machine run (notice the
TEMP_SSH, using the value from step #2 above):
nix run github:nix-community/nixos-anywhere -- --generate-hardware-config nixos-facter ./hosts/thenixbeast/facter.json --extra-files "$TEMP_SSH" --phases kexec,install,reboot --flake .#thenixbeast --target-host root@<ip address>
After the host's SSH key is in .sops.yaml (step 3 above):
- If it will push to the cache or send builds, add its key to the
modules/(attic-push|distributed_builders)/secrets.yamlrule in.sops.yaml, thensops updatekeys modules/attic-push/secrets.yaml modules/distributed_builders/secrets.yaml. That's all it needs for the cache: there's no token to mint. - Add its host key to
programs.ssh.knownHostsinmodules/distributed_builders, and to the mini-nas repo's copy. - In
flake.nix, import./modules/attic-pushto push its builds, and./modules/distributed_buildersto setmy.distributedBuilders.builders(only hosts faster than it) oracceptBuilds. A host that accepts builds also needs an entry in that module'smachines, sized as described there. - Set
coresandmax-jobsin itshosts/<host>/default.nixso thatmax-jobs * coresis twice its threads, as on the other hosts. - In the mini-nas repo, add it to the
build dotfiles …line inmodules/nightly_config_builder, so the cache is warm for it.
Once tailscale is installed and running on your system, join the network by:
- Run
tailscale up --login-server=https://headscale.immortalkeep.com - Via a connection to the headscale server, run the command it gives you to register the node. In this case, we're going to do so using kubectl:
a. Find/confirm which username to register the node under:
kubectl exec -n apps headscale-abcdef-0123 -- headscale users listb.kubectl exec -n apps headscale-abcdef-0123 -- headscale nodes register --user {username_from_above} --key mkey:0123456789abcdef... - You may also want to rename the node in headscale:
a. Get the numeric ID of the node:
kubectl exec -n apps headscale-abcdef-0123 -- headscale nodes listb. Using the numeric ID as the index, give the node a new name:headscale nodes rename -i 7 new-name
- List network interfaces:
nmcli device - List nearby networks:
nm device wifi list - Connect:
nm device wifi connect {network_name} --ask - Disconnect:
nm device disconnect {wifi_interface_name}
There are non-nix-related top level directories in the repo. These are my old dotfiles, that I used to instantiate on a machine using stow which would smoothly create symlinks between the ~/.config folder and these folders - making it easy for me to keep this repo up to date and deploy new stuff. Now though, I've mostly moved over to using Nix and I'll remove old dotfile directories if it seems I'm never going to use them again.
- chunkwm: project is no longer developed. Move to
yabaiinstead. - fish: configuration moved to
home.nix, now ceasing to maintain thefishdirectory. - sway: configuration moved to
modules/sway/default.nix. I've ceased to maintain theswaydotfiles independently, because I can't imagine setting up a new desktop environment and not using nix to do it. - termite: terminal deprecated. Author recommends using
alacrittyinstead. - terminator: abandoned by the original devs and then picked up again by new enthusiasts. For me though,
alacritty+tmuxis cleaner. - urxvt: hopefully I never need return to the
Xwindow system.alacritty+tmuxotherwise preferred. - zsh: ceasing to maintain the configuration files.
fishhas all the shell niceness, batteries included.