Files
hermenix/docs/MANUAL_SETUP.md
2026-10-09 14:35:12 -04:00

2.9 KiB

Manual setup

What hermenix setup does, step by step, for hand-running or when something goes sideways. Prefer the guided command in INSTALL.md when you can.

1. Create the disks

Two disks — design in CONCEPTS.md.

sudo btrfs subvolume create /var/lib/hermes-vm/system
sudo btrfs subvolume create /var/lib/hermes-vm/state
sudo mkdir -p /var/lib/hermes-vm/snapshots

# BEFORE creating any file inside them
sudo chattr +C /var/lib/hermes-vm/system /var/lib/hermes-vm/state
sudo btrfs property set /var/lib/hermes-vm/system compression none
sudo btrfs property set /var/lib/hermes-vm/state compression none

sudo truncate -s 80G /var/lib/hermes-vm/system/system.raw
sudo truncate -s 20G /var/lib/hermes-vm/state/state.raw
sudo mkfs.ext4 -L hermes-state /var/lib/hermes-vm/state/state.raw

chattr +C ordering matters. Btrfs CoW stacked under a VM disk image fragments badly. +C disables that — but only for files created after. Set it on empty subvolumes and confirm with lsattr before writing anything. Wrong order → recreate the subvolume and copy the image in fresh.

Separate subvolumes so a btrfs snapshot of state does not include the system image.

2. Generate the cache signing key

The host serves its store to the guest as a read-only binary cache.

sudo mkdir -p /var/lib/secrets
sudo nix-store --generate-binary-cache-key hermes-cache-1 \
  /var/lib/secrets/hermes-cache.secret /var/lib/secrets/hermes-cache.pub
sudo chown nix-serve /var/lib/secrets/hermes-cache.secret
sudo chmod 0400 /var/lib/secrets/hermes-cache.secret
cat /var/lib/secrets/hermes-cache.pub

3. Write /etc/hermenix/local.nix

Host-specific settings live here, not in this repo — see guest/local.nix.example:

{
  cachePublicKey = "hermes-cache-1:AbCd..."; # key you just printed; empty = skip host cache
  authorizedKeys = [ "ssh-ed25519 AAAA... you@laptop" ];
}

sudo mkdir -p /etc/hermenix first if needed.

4. Build the image and write it to the system disk

--impure is required because guest/common.nix reads /etc/hermenix/local.nix outside the flake source tree. The extra substituter flags avoid compiling Determinate Nix from source. setup also passes --no-write-lock-file --refresh when building from the git URL — mirror that if you're doing the same by hand.

nix build --impure --no-write-lock-file --refresh \
  git+ssh://gitea@gitea.skyg.ca/ari/hermenix.git#hermes-guest-image \
  --option extra-substituters https://install.determinate.systems \
  --option extra-trusted-public-keys cache.flakehub.com-3:hJuILl5sVK4iKm86JzgdXW12Y2Hwd5G07qKtHTOcDCM=

# notrunc keeps the disk at its full size; the image is smaller
sudo dd if=result/nixos.img of=/var/lib/hermes-vm/system/system.raw \
  bs=4M conv=notrunc,fsync status=progress

From a local checkout, use . instead of the git URL (still --impure).

5. Module + first boot

Continue from INSTALL.md.