NixOS Initial Setup

Target(right): machine on which NixOS will be installed upon

Executor(left): machine where you’ll run nixos-anywhere from

Prerequisites

Enter BIOS and proceed as follows:

Key Reference to Enter BIOS
Machine Key
Server Del
Desktop F2
Laptop F2

Desktop

Disable CSM support and Secure Boot (the latter will be enabled afterwards)

  1. Switch to Advanced Mode (F2)
  2. Navigate to Boot
  3. Set CSM Support to disabled
  4. Enter Secure Boot
  5. Set Secure Boot to disabled

Set UEFI/Administrator password

  1. Switch to Advanced Mode (F2)

  2. Navigate to Boot

  3. Set Security Option to Setup

    So that password is only required when accessing BIOS and not at system boot

  4. Select Administrator Password

  5. Enter password

Installation & Deployment

Live-boot a minimal NixOS image on the target machine, then configure as follows:

Escalate privileges and prepare the environment

sudo -i
loadkeys es
passwd # set a temporary password for setup
systemctl start sshd

Generate LUKS decryption key

dd if=/dev/urandom bs=1 count=32 | base64 > /tmp/pass
Wipe unused boot partitions if any with efibootmgr

List entries along with their IDs

sudo efibootmgr

Delete entry

sudo efibootmgr -b <ID> -B

Run nixos-anywhere

Server

nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#server' \
  --phases 'kexec,disko' \
  --generate-hardware-config nixos-facter hosts/server/facter.json \
  --show-trace \
  'root@<target_machine_IP>'

Desktop

nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#desktop' \
  --phases 'kexec,disko' \
  --generate-hardware-config nixos-facter hosts/desktop/facter.json \
  --show-trace \
  'root@<target_machine_IP>'

Laptop

nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#laptop' \
  --phases 'kexec,disko' \
  --generate-hardware-config nixos-facter hosts/laptop/facter.json \
  --show-trace \
  'root@<target_machine_IP>'

Potato

Installs to removable storage, so confirm the by-id path resolves to that drive and not to a data disk before running anything destructive

ssh root@<target_machine_IP> 'readlink -f /dev/disk/by-id/usb-<drive>; lsblk -dno NAME,SIZE,TRAN,MODEL'
nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#potato' \
  --phases 'kexec,disko' \
  --generate-hardware-config nixos-facter hosts/potato/facter.json \
  --show-trace \
  'root@<target_machine_IP>'

nixos-anywhere skips kexec when the target already runs a NixOS installer, which is what leaves /tmp/pass intact between phases. Reference USB Boot (potato) for why this host exists.

Reinstalling the server: restore the backup before installing

The backup carries the server’s host keys, sops age key and UID/GID map, so it is restored after the disko phase and before the install, which skips the two key steps below. Reference Server Reinstall for the full procedure, from the final backup to the post-install rebuilds.

Set up SSH hosts

mkdir -p /mnt/persist/etc/secrets/initrd
ssh-keygen -t ed25519 -f /mnt/persist/etc/secrets/initrd/ssh_host_ed25519_key -N "" -C ""
chmod 400 /mnt/persist/etc/secrets/initrd/*

Set Age private keys for sops-nix

mkdir -p /mnt/persist/var/keys
vim /mnt/persist/var/keys/sops-nix

Install bootstrap profile

BOOTSTRAP=1 selects a minimal feature whitelist (boot, network, SSH, sops, users) so the install-phase tmpfs doesn’t OOM on heavy services. Impure evaluation is required because the env var is read via builtins.getEnv. Reference values/bootstrap.nix for the whitelist.

Installing while git.yhkze.net is unavailable

The dotfiles and yobidashi inputs are served by the server’s own Forgejo, so reinstalling the server means they cannot be fetched from it. Evaluation happens on the executor, not the target, and every deployed host keeps both sources in its system closure, so an executor that has run rebuild at least once already holds them and needs nothing here.

Export the following only when the executor is itself cold — a fresh live ISO, or a machine whose store has never held these inputs. Both repositories are mirrored to Codeberg under the same yuuhikaze/ path, so one rule covers both.

export GIT_CONFIG_COUNT=1
export GIT_CONFIG_KEY_0='url.https://codeberg.org/yuuhikaze/.insteadOf'
export GIT_CONFIG_VALUE_0='https://git.yhkze.net/yuuhikaze/'

Nix shells out to git, so the rewrite redirects the fetch while flake.lock keeps recording the Forgejo URL. The mirror must carry the locked revision; if it has fallen behind, the fetch resolves to a different commit than the lock pins.

Server

BOOTSTRAP=1 nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#server' \
  --option pure-eval false \
  --phases 'install,reboot' \
  --show-trace \
  'root@<target_machine_IP>'

Desktop

BOOTSTRAP=1 nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#desktop' \
  --option pure-eval false \
  --phases 'install,reboot' \
  --show-trace \
  'root@<target_machine_IP>'

Laptop

BOOTSTRAP=1 nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#laptop' \
  --option pure-eval false \
  --phases 'install,reboot' \
  --show-trace \
  'root@<target_machine_IP>'

Potato

BOOTSTRAP=1 nix run nixpkgs#nixos-anywhere \
  --extra-experimental-features 'nix-command flakes' \
  -- --flake 'path:.#potato' \
  --option pure-eval false \
  --phases 'install,reboot' \
  --show-trace \
  'root@<target_machine_IP>'

Once system reboots, unlock LUKS disk encryption via SSH

The initrd brings up networking and an sshd on port 2224 to take the passphrase before sysroot.mount runs.

flowchart LR
    A[power on] --> B[initrd]
    B --> C[dhcp + sshd:2224]
    C --> D[passphrase over ssh]
    D --> E[LUKS opens crypted-nvme]
    E --> F[sysroot.mount, normal boot]
cat <<< "<pass>" | ssh -p 2224 root@<target_machine_IP> systemd-tty-ask-password-agent

This action is required on every boot until TPM2 auto-unlock is enabled

Converge to full configuration

The bootstrap profile omits most services, so switch to the host’s real feature list. Build on the executor and push the closure rather than building on the target

rebuild push <target_machine_IP>

Post-Install Steps

Secure Boot

Reference secure-boot.md for complete Secure Boot setup with Lanzaboote and sbctl.

Maintenance

Secrets Management

For more information, watch: https://youtube.com/watch?v=G5f6GC7SnhU

Derive Age keys from SSH and manage secrets file

nix run nixpkgs#ssh-to-age -- -private-key -i ~/.ssh/id_ed25519 > /var/keys/sops-nix

Display public Age key for .sops.yaml config

nix shell nixpkgs#age -c age-keygen -y /var/keys/sops-nix

Edit secrets

nix run nixpkgs#sops -- secrets.yaml

System Updates

The flake has two categories of inputs: tracked inputs, which follow their branch on every update, and pinned inputs — packages whose upstream changes break things or that must move in lockstep with something else (the extra nixpkgs instances such as anki-suite, trilium and hyprland-suite, plus the invidious-companion fork). nix flake update with no arguments bumps both categories, so it is not used for routine updates.

The pinned set is lib.pinnedInputs in the outputs of flake.nix. A new pinned input goes into that list in the same change that adds it. The update script guards the common case: it refuses to run while a root input locked from NixOS/nixpkgs is neither listed there nor one of the tracked nixpkgs and nixpkgs-unstable. A pinned input from any other source (like the invidious-companion fork) has no such guard.

Routine update — update every root input except the pinned ones:

update

Preview which inputs would be updated and which are held back, without touching flake.lock:

update --dry-run

Then rebuild each host:

rebuild 10.100.0.1
rebuild 10.100.0.2
rebuild

Update a specific pinned input when ready to take on breakage:

nix flake update hyprland-suite   # any name from lib.pinnedInputs
rebuild                            # rebuild affected hosts afterwards

Major NixOS version upgrade (e.g. 26.05 → 26.11) — bump the four versioned input URLs in flake.nix:

Then run update, bump the pinned inputs that track nixos-26.05 one by name each, and read the release notes before rebuilding. Do not bump system.stateVersion — it stays at the install-time value.

Garbage Collection

Delete unreferenced store paths

sudo nix-collect-garbage

Delete old generations

nix-collect-garbage -d
# nix-env --delete-generations 10-20

Optimise store (deletes duplicate files in Nix store)

nix store optimise

Impermanence

When declaring a new file or directory as non-impermanent, first move it to persistent storage, then rebuild the system.

mv /path/to/persist /persist/destination/path/

Where persist can be either a directory or file