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

85 lines
2.9 KiB
Markdown

# Manual setup
What `hermenix setup` does, step by step, for hand-running or when something
goes sideways. Prefer the guided command in [INSTALL.md](INSTALL.md) when you
can.
## 1. Create the disks
Two disks — design in [CONCEPTS.md](CONCEPTS.md#two-disks).
```bash
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.
```bash
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`:
```nix
{
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.
```bash
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](INSTALL.md#add-the-module).