doc clean
This commit is contained in:
1 parent
c2a7f94821
commit
30427e3975
34 files changed
+1119
-1758
No files matched your search
@@ -0,0 +1,84 @@
|
||||
# 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).
|
||||
Reference in new issue
Block a user